diff --git a/app/App/Providers/ThemeServiceProvider.php b/app/App/Providers/ThemeServiceProvider.php index 2cf581d3863..50c76bbf846 100644 --- a/app/App/Providers/ThemeServiceProvider.php +++ b/app/App/Providers/ThemeServiceProvider.php @@ -4,6 +4,8 @@ use BookStack\Theming\ThemeEvents; use BookStack\Theming\ThemeService; +use BookStack\Theming\ThemeViews; +use Illuminate\Support\Facades\Blade; use Illuminate\Support\ServiceProvider; class ThemeServiceProvider extends ServiceProvider @@ -24,7 +26,23 @@ public function boot(): void { // Boot up the theme system $themeService = $this->app->make(ThemeService::class); + $viewFactory = $this->app->make('view'); + if (!$themeService->getTheme()) { + return; + } + + $themeService->loadModules(); $themeService->readThemeActions(); $themeService->dispatch(ThemeEvents::APP_BOOT, $this->app); + + $themeViews = new ThemeViews(); + $themeService->dispatch(ThemeEvents::THEME_REGISTER_VIEWS, $themeViews); + $themeViews->registerViewPathsForTheme($viewFactory->getFinder(), $themeService->getModules()); + if ($themeViews->hasRegisteredViews()) { + $viewFactory->share('__themeViews', $themeViews); + Blade::directive('include', function ($expression) { + return "handleViewInclude({$expression}, array_diff_key(get_defined_vars(), ['__data' => 1, '__path' => 1])); ?>"; + }); + } } } diff --git a/app/App/helpers.php b/app/App/helpers.php index 0e357e36aee..8f210ecafd4 100644 --- a/app/App/helpers.php +++ b/app/App/helpers.php @@ -81,8 +81,7 @@ function setting(?string $key = null, mixed $default = null): mixed /** * Get a path to a theme resource. - * Returns null if a theme is not configured and - * therefore a full path is not available for use. + * Returns null if a theme is not configured, and therefore a full path is not available for use. */ function theme_path(string $path = ''): ?string { diff --git a/app/Config/view.php b/app/Config/view.php index 80bc9ef8fe8..2eb30b4c9de 100644 --- a/app/Config/view.php +++ b/app/Config/view.php @@ -8,12 +8,6 @@ * Do not edit this file unless you're happy to maintain any changes yourself. */ -// Join up possible view locations -$viewPaths = [realpath(base_path('resources/views'))]; -if ($theme = env('APP_THEME', false)) { - array_unshift($viewPaths, base_path('themes/' . $theme)); -} - return [ // App theme @@ -26,7 +20,7 @@ // Most templating systems load templates from disk. Here you may specify // an array of paths that should be checked for your views. Of course // the usual Laravel view path has already been registered for you. - 'paths' => $viewPaths, + 'paths' => [realpath(base_path('resources/views'))], // Compiled View Path // This option determines where all the compiled Blade templates will be diff --git a/app/Theming/ThemeController.php b/app/Theming/ThemeController.php index 1eecc697428..c2676780371 100644 --- a/app/Theming/ThemeController.php +++ b/app/Theming/ThemeController.php @@ -5,21 +5,22 @@ use BookStack\Facades\Theme; use BookStack\Http\Controller; use BookStack\Util\FilePathNormalizer; +use Symfony\Component\HttpFoundation\StreamedResponse; class ThemeController extends Controller { /** * Serve a public file from the configured theme. */ - public function publicFile(string $theme, string $path) + public function publicFile(string $theme, string $path): StreamedResponse { $cleanPath = FilePathNormalizer::normalize($path); if ($theme !== Theme::getTheme() || !$cleanPath) { abort(404); } - $filePath = theme_path("public/{$cleanPath}"); - if (!file_exists($filePath)) { + $filePath = Theme::findFirstFile("public/{$cleanPath}"); + if (!$filePath) { abort(404); } diff --git a/app/Theming/ThemeEvents.php b/app/Theming/ThemeEvents.php index 44630acaeb1..c6266b32b9c 100644 --- a/app/Theming/ThemeEvents.php +++ b/app/Theming/ThemeEvents.php @@ -134,6 +134,16 @@ class ThemeEvents */ const ROUTES_REGISTER_WEB_AUTH = 'routes_register_web_auth'; + + /** + * Theme register views event. + * Called by the theme system when a theme is active, so that custom view templates can be registered + * to be rendered in addition to existing app views. + * + * @param \BookStack\Theming\ThemeViews $themeViews + */ + const THEME_REGISTER_VIEWS = 'theme_register_views'; + /** * Web before middleware action. * Runs before the request is handled but after all other middleware apart from those diff --git a/app/Theming/ThemeModule.php b/app/Theming/ThemeModule.php new file mode 100644 index 00000000000..12b1486beda --- /dev/null +++ b/app/Theming/ThemeModule.php @@ -0,0 +1,56 @@ +folderName}/{$component}"); + } +} diff --git a/app/Theming/ThemeService.php b/app/Theming/ThemeService.php index 4bdb6836b02..6f31129804c 100644 --- a/app/Theming/ThemeService.php +++ b/app/Theming/ThemeService.php @@ -6,6 +6,7 @@ use BookStack\Exceptions\ThemeException; use Illuminate\Console\Application; use Illuminate\Console\Application as Artisan; +use Illuminate\View\FileViewFinder; use Symfony\Component\Console\Command\Command; class ThemeService @@ -15,6 +16,11 @@ class ThemeService */ protected array $listeners = []; + /** + * @var array + */ + protected array $modules = []; + /** * Get the currently configured theme. * Returns an empty string if not configured. @@ -76,20 +82,96 @@ public function registerCommand(Command $command): void } /** - * Read any actions from the set theme path if the 'functions.php' file exists. + * Read any actions from the 'functions.php' file of the active theme or its modules. */ public function readThemeActions(): void { - $themeActionsFile = theme_path('functions.php'); - if ($themeActionsFile && file_exists($themeActionsFile)) { + $moduleFunctionFiles = array_map(function (ThemeModule $module): string { + return $module->path('functions.php'); + }, $this->modules); + $allFunctionFiles = array_merge(array_values($moduleFunctionFiles), [theme_path('functions.php')]); + $filteredFunctionFiles = array_filter($allFunctionFiles, function (string $file): bool { + return $file && file_exists($file); + }); + + foreach ($filteredFunctionFiles as $functionFile) { try { - require $themeActionsFile; + require $functionFile; } catch (\Error $exception) { - throw new ThemeException("Failed loading theme functions file at \"{$themeActionsFile}\" with error: {$exception->getMessage()}"); + throw new ThemeException("Failed loading theme functions file at \"{$functionFile}\" with error: {$exception->getMessage()}"); + } + } + } + + /** + * Read the modules folder and load in any valid theme modules. + */ + public function loadModules(): void + { + $modulesFolder = theme_path('modules'); + if (!$modulesFolder || !is_dir($modulesFolder)) { + return; + } + + $subFolders = array_filter(scandir($modulesFolder), function ($item) use ($modulesFolder) { + return $item !== '.' && $item !== '..' && is_dir($modulesFolder . DIRECTORY_SEPARATOR . $item); + }); + + foreach ($subFolders as $folderName) { + $moduleJsonFile = $modulesFolder . DIRECTORY_SEPARATOR . $folderName . DIRECTORY_SEPARATOR . 'bookstack-module.json'; + + if (!file_exists($moduleJsonFile)) { + continue; + } + + try { + $jsonContent = file_get_contents($moduleJsonFile); + $jsonData = json_decode($jsonContent, true); + + if (json_last_error() !== JSON_ERROR_NONE) { + throw new ThemeException("Invalid JSON in module file at \"{$moduleJsonFile}\": " . json_last_error_msg()); + } + + $module = ThemeModule::fromJson($jsonData, $folderName); + $this->modules[$folderName] = $module; + } catch (ThemeException $exception) { + throw $exception; + } catch (\Exception $exception) { + throw new ThemeException("Failed loading module from \"{$moduleJsonFile}\" with error: {$exception->getMessage()}"); } } } + /** + * Get all loaded theme modules. + * @return array + */ + public function getModules(): array + { + return $this->modules; + } + + /** + * Look for a specific file within the theme or its modules. + * Returns the first file found or null if not found. + */ + public function findFirstFile(string $path): ?string + { + $themePath = theme_path($path); + if (file_exists($themePath)) { + return $themePath; + } + + foreach ($this->modules as $module) { + $customizedFile = $module->path($path); + if (file_exists($customizedFile)) { + return $customizedFile; + } + } + + return null; + } + /** * @see SocialDriverManager::addSocialDriver */ diff --git a/app/Theming/ThemeViews.php b/app/Theming/ThemeViews.php new file mode 100644 index 00000000000..b2d0adc02f6 --- /dev/null +++ b/app/Theming/ThemeViews.php @@ -0,0 +1,104 @@ +> + */ + protected array $beforeViews = []; + + /** + * @var array> + */ + protected array $afterViews = []; + + /** + * Register any extra paths for where we may expect views to be located + * with the provided FileViewFinder, to make custom views available for use. + * @param ThemeModule[] $modules + */ + public function registerViewPathsForTheme(FileViewFinder $finder, array $modules): void + { + foreach ($modules as $module) { + $moduleViewsPath = $module->path('views'); + if (file_exists($moduleViewsPath) && is_dir($moduleViewsPath)) { + $finder->prependLocation($moduleViewsPath); + } + } + + $finder->prependLocation(theme_path()); + } + + /** + * Provide the response for a blade template view include. + */ + public function handleViewInclude(string $viewPath, array $data = []): string + { + if (!$this->hasRegisteredViews()) { + return view()->make($viewPath, $data)->render(); + } + + $viewsContent = [ + ...$this->renderViewSets($this->beforeViews[$viewPath] ?? [], $data), + view()->make($viewPath, $data)->render(), + ...$this->renderViewSets($this->afterViews[$viewPath] ?? [], $data), + ]; + + return implode("\n", $viewsContent); + } + + /** + * Register a custom view to be rendered before the given target view is included in the template system. + */ + public function renderBefore(string $targetView, string $localView, int $priority = 50): void + { + $this->registerAdjacentView($this->beforeViews, $targetView, $localView, $priority); + } + + /** + * Register a custom view to be rendered after the given target view is included in the template system. + */ + public function renderAfter(string $targetView, string $localView, int $priority = 50): void + { + $this->registerAdjacentView($this->afterViews, $targetView, $localView, $priority); + } + + public function hasRegisteredViews(): bool + { + return !empty($this->beforeViews) && !empty($this->afterViews); + } + + protected function registerAdjacentView(array &$location, string $targetView, string $localView, int $priority = 50): void + { + $viewPath = theme_path($localView . '.blade.php'); + if (!file_exists($viewPath)) { + throw new ThemeException("Expected registered view file at \"{$viewPath}\" does not exist"); + } + + if (!isset($location[$targetView])) { + $location[$targetView] = []; + } + $location[$targetView][$viewPath] = $priority; + } + + /** + * @param array $viewSet + * @return string[] + */ + protected function renderViewSets(array $viewSet, array $data): array + { + $paths = array_keys($viewSet); + usort($paths, function (string $a, string $b) use ($viewSet) { + return $viewSet[$a] <=> $viewSet[$b]; + }); + + return array_map(function (string $viewPath) use ($data) { + return view()->file($viewPath, $data)->render(); + }, $paths); + } +} diff --git a/app/Translation/FileLoader.php b/app/Translation/FileLoader.php index 1fec4d18bb1..6212506ddf6 100644 --- a/app/Translation/FileLoader.php +++ b/app/Translation/FileLoader.php @@ -2,6 +2,7 @@ namespace BookStack\Translation; +use BookStack\Facades\Theme; use Illuminate\Translation\FileLoader as BaseLoader; class FileLoader extends BaseLoader @@ -12,11 +13,6 @@ class FileLoader extends BaseLoader * Extends Laravel's translation FileLoader to look in multiple directories * so that we can load in translation overrides from the theme file if wanted. * - * Note: As of using Laravel 10, this may now be redundant since Laravel's - * file loader supports multiple paths. This needs further testing though - * to confirm if Laravel works how we expect, since we specifically need - * the theme folder to be able to partially override core lang files. - * * @param string $locale * @param string $group * @param string|null $namespace @@ -32,9 +28,18 @@ public function load($locale, $group, $namespace = null): array if (is_null($namespace) || $namespace === '*') { $themePath = theme_path('lang'); $themeTranslations = $themePath ? $this->loadPaths([$themePath], $locale, $group) : []; - $originalTranslations = $this->loadPaths($this->paths, $locale, $group); - return array_merge($originalTranslations, $themeTranslations); + $modules = Theme::getModules(); + $moduleTranslations = []; + foreach ($modules as $module) { + $modulePath = $module->path('lang'); + if (file_exists($modulePath)) { + $moduleTranslations = array_merge($moduleTranslations, $this->loadPaths([$modulePath], $locale, $group)); + } + } + + $originalTranslations = $this->loadPaths($this->paths, $locale, $group); + return array_merge($originalTranslations, $moduleTranslations, $themeTranslations); } return $this->loadNamespaced($locale, $group, $namespace); diff --git a/app/Util/SvgIcon.php b/app/Util/SvgIcon.php index ce6e1c23e37..b1b14a4872a 100644 --- a/app/Util/SvgIcon.php +++ b/app/Util/SvgIcon.php @@ -2,6 +2,8 @@ namespace BookStack\Util; +use BookStack\Facades\Theme; + class SvgIcon { public function __construct( @@ -23,12 +25,9 @@ public function toHtml(): string $attrString .= $attrName . '="' . $attr . '" '; } - $iconPath = resource_path('icons/' . $this->name . '.svg'); - $themeIconPath = theme_path('icons/' . $this->name . '.svg'); - - if ($themeIconPath && file_exists($themeIconPath)) { - $iconPath = $themeIconPath; - } elseif (!file_exists($iconPath)) { + $defaultIconPath = resource_path('icons/' . $this->name . '.svg'); + $iconPath = Theme::findFirstFile("icons/{$this->name}.svg") ?? $defaultIconPath; + if (!file_exists($iconPath)) { return ''; } diff --git a/dev/docs/logical-theme-system.md b/dev/docs/logical-theme-system.md index 0063c4e8bac..9457ca78b52 100644 --- a/dev/docs/logical-theme-system.md +++ b/dev/docs/logical-theme-system.md @@ -99,6 +99,41 @@ Theme::listen(ThemeEvents::APP_BOOT, function($app) { }); ``` +## Custom View Registration Example + +Using the logical theme system, you can register custom views to be rendered before/after other existing views, providing a flexible way to add content without needing to override and/or replicate existing content. This is done by listening to the `THEME_REGISTER_VIEWS`. + +**Note:** You don't need to use this to override existing views, or register whole new main views to use, since that's done automatically based on their existence. This is just for advanced capabilities like inserting before/after existing views. + +This event provides a `ThemeViews` instance which has the following methods made available: + +- `renderBefore(string $targetView, string $localView, int $priority)` +- `renderAfter(string $targetView, string $localView, int $priority)` + +The target view is the name of that which we want to insert our custom view relative to. +The local view is the name of the view we want to add and render. +The priority provides a suggestion to the ordering of view display, with lower numbers being shown first. This defaults to 50 if not provided. + +Here's an example of this in use: + +```php +renderBefore('layouts.parts.header', 'welcome-banner', 4); + $themeViews->renderAfter('layouts.parts.header', 'information-alert'); + $themeViews->renderAfter('layouts.parts.header', 'additions.password-notice', 20); +}); +``` + +In this example, we're inserting custom views before and after the main header bar. +BookStack will look for a `welcome-banner.blade.php` file within our theme folder (or a theme module view folder) to render before the header. It'll look for the `information-alert.blade.php` and `additions/password-notice.blade.php` views to render afterwards. +The password notice will be shown above the information alert view, since it has a specified priority of 20, whereas the information alert view would default to a priority of 50. + ## Custom Command Registration Example The logical theme system supports adding custom [artisan commands](https://laravel.com/docs/8.x/artisan) to BookStack. diff --git a/dev/docs/theme-system-modules.md b/dev/docs/theme-system-modules.md new file mode 100644 index 00000000000..c25a6024113 --- /dev/null +++ b/dev/docs/theme-system-modules.md @@ -0,0 +1,60 @@ +# Theme System Modules + +A theme system module is a collection of customizations using the [visual](visual-theme-system.md) and [logical](logical-theme-system.md) theme systems, provided along with some metadata, that can be installed alongside other modules within a theme. They can effectively be thought of as "plugins" or "extensions" that can be applied in addition to any customizations in the active theme. + +### Module Location + +Modules are contained within a folder themselves, which should be located inside a `modules` folder within a [BookStack theme folder](visual-theme-system.md#getting-started). +As an example, starting from the `themes/` top-level folder of a BookStack instance: + +```txt +themes +└── my-theme + └── modules + ├── module-a + │ └── bookstack-module.json + └── module-b + └── bookstack-module.json +``` + +### Module Format + +A module exists as a folder in the location [as detailed above](#module-location). +The content within the module folder should then follow this format: + +- `bookstack-module.json` - REQUIRED - A JSON file containing [the metadata](#module-json-metadata) for the module. +- `functions.php` - OPTIONAL - A PHP file containing code for the [logical theme system](logical-theme-system.md). +- `icons/` - OPTIONAL - A folder containing any icons to use as per [the visual theme system](visual-theme-system.md#customizing-icons). +- `lang/` - OPTIONAL - A folder containing any language files to use as per [the visual theme system](visual-theme-system.md#customizing-text-content). +- `public/` - OPTIONAL - A folder containing any files to expose into public web-space as per [the visual theme system](visual-theme-system.md#publicly-accessible-files). +- `views/` - OPTIONAL - A folder containing any view additions or overrides as per [the visual theme system](visual-theme-system.md#customizing-view-files). + +You can create additional directories/files for your own needs within the module, but ideally name them something unique to prevent conflicts with the above structure. + +### Module JSON Metadata + +Modules are required to have a `bookstack-module.json` file in the top level directory of the module. +This must be a JSON file with the following properties: + +- `name` - string - An (ideally unique) name for the module. +- `description` - string - A short description of the module. +- `version` - string - A string version number generally following [semantic versioning](https://semver.org/). + - Examples: `v0.4.0`, `4.3.12`, `v0.1.0-beta4`. + +### Customization Order/Precedence + +It's possible that multiple modules may override/customize the same content. +Right now, there's no assurance in regard to the order in which modules may be loaded. +Generally they will be used/searched in order of their module folder name, but this is not assured and should not be relied upon. + +It's also possible that modules customize the same content as the configured theme. +In this scenario, the theme takes precedence. Modules are designed to be more portable and instance abstract, whereas the theme folder would typically be specific to the instance. +This allows the theme to be used to customize or override module content for the BookStack instance, without altering the module code itself. + +### Module Best Practices + +Here are some general best practices when it comes to creating modules: + +- Use a unique name and clear description so the user can understand the purpose of the module. +- Increment the metadata version on change, keeping to [semver](https://semver.org/) to indicate compatibility of new versions. +- Where possible, prefer to [insert views before/after](logical-theme-system.md#custom-view-registration-example) instead of overriding existing views, to reduce likelihood of conflicts or update troubles. \ No newline at end of file diff --git a/dev/docs/visual-theme-system.md b/dev/docs/visual-theme-system.md index 8a76ddb00e0..8d5669b82bf 100644 --- a/dev/docs/visual-theme-system.md +++ b/dev/docs/visual-theme-system.md @@ -4,7 +4,7 @@ BookStack allows visual customization via the theme system which enables you to This is part of the theme system alongside the [logical theme system](./logical-theme-system.md). -**Note:** This theme system itself is maintained and supported but usages of this system, including the files you are able to override, are not considered stable and may change upon any update. You should test any customizations made after updates. +**Note:** This theme system itself is maintained and supported, but usages of this system, including the files you are able to override, are not considered stable and may change upon any update. You should test any customizations made after updates. ## Getting Started @@ -18,6 +18,9 @@ You'll need to tell BookStack to use your theme via the `APP_THEME` option in yo Content placed in your `themes//` folder will override the original view files found in the `resources/views` folder. These files are typically [Laravel Blade](https://laravel.com/docs/10.x/blade) files. As an example, I could override the `resources/views/books/parts/list-item.blade.php` file with my own template at the path `themes//books/parts/list-item.blade.php`. +In addition to overriding original views, this could be used to add new views for use via the [logical theme system](logical-theme-system.md). +By using the `THEME_REGISTER_VIEWS` logical event, you can also register your views to be rendered before/after existing views. An example of this can be found in our [logical theme guidance](logical-theme-system.md#custom-view-registration-example). + ## Customizing Icons SVG files placed in a `themes//icons` folder will override any icons of the same name within `resources/icons`. You'd typically want to follow the format convention of the existing icons, where no XML deceleration is included and no width & height attributes are set, to ensure optimal compatibility. diff --git a/tests/TestCase.php b/tests/TestCase.php index f69f20d4c55..c6f811b3158 100644 --- a/tests/TestCase.php +++ b/tests/TestCase.php @@ -13,6 +13,7 @@ use Illuminate\Http\JsonResponse; use Illuminate\Support\Env; use Illuminate\Support\Facades\DB; +use Illuminate\Support\Facades\File; use Illuminate\Support\Facades\Log; use Illuminate\Testing\Assert as PHPUnit; use Illuminate\Testing\Constraints\HasInDatabase; @@ -157,6 +158,23 @@ protected function runWithEnv(array $valuesByKey, callable $callback, bool $hand } } + protected function usingThemeFolder(callable $callback): void + { + // Create a folder and configure a theme + $themeFolderName = 'testing_theme_' . str_shuffle(rtrim(base64_encode(time()), '=')); + config()->set('view.theme', $themeFolderName); + $themeFolderPath = theme_path(''); + + // Create a theme folder and clean it up on application tear-down + File::makeDirectory($themeFolderPath); + $this->beforeApplicationDestroyed(fn() => File::deleteDirectory($themeFolderPath)); + + // Run provided callback with the theme env option set + $this->runWithEnv(['APP_THEME' => $themeFolderName], function () use ($callback, $themeFolderName) { + call_user_func($callback, $themeFolderName); + }); + } + /** * Check the keys and properties in the given map to include * exist, albeit not exclusively, within the map to check. diff --git a/tests/Theme/LogicalThemeEventsTest.php b/tests/Theme/LogicalThemeEventsTest.php new file mode 100644 index 00000000000..0a4afd2f4e3 --- /dev/null +++ b/tests/Theme/LogicalThemeEventsTest.php @@ -0,0 +1,321 @@ +assertInstanceOf(Environment::class, $environment); + $callbackCalled = true; + + return $environment; + }; + Theme::listen(ThemeEvents::COMMONMARK_ENVIRONMENT_CONFIGURE, $callback); + + $page = $this->entities->page(); + $content = new PageContent($page); + $content->setNewMarkdown('# test', $this->users->editor()); + + $this->assertTrue($callbackCalled); + } + + public function test_web_middleware_before() + { + $callbackCalled = false; + $requestParam = null; + $callback = function ($request) use (&$callbackCalled, &$requestParam) { + $requestParam = $request; + $callbackCalled = true; + }; + + Theme::listen(ThemeEvents::WEB_MIDDLEWARE_BEFORE, $callback); + $this->get('/login', ['Donkey' => 'cat']); + + $this->assertTrue($callbackCalled); + $this->assertInstanceOf(Request::class, $requestParam); + $this->assertEquals('cat', $requestParam->header('donkey')); + } + + public function test_web_middleware_before_return_val_used_as_response() + { + $callback = function (Request $request) { + return response('cat', 412); + }; + + Theme::listen(ThemeEvents::WEB_MIDDLEWARE_BEFORE, $callback); + $resp = $this->get('/login', ['Donkey' => 'cat']); + $resp->assertSee('cat'); + $resp->assertStatus(412); + } + + public function test_web_middleware_after() + { + $callbackCalled = false; + $requestParam = null; + $responseParam = null; + $callback = function ($request, Response $response) use (&$callbackCalled, &$requestParam, &$responseParam) { + $requestParam = $request; + $responseParam = $response; + $callbackCalled = true; + $response->header('donkey', 'cat123'); + }; + + Theme::listen(ThemeEvents::WEB_MIDDLEWARE_AFTER, $callback); + + $resp = $this->get('/login', ['Donkey' => 'cat']); + $this->assertTrue($callbackCalled); + $this->assertInstanceOf(Request::class, $requestParam); + $this->assertInstanceOf(Response::class, $responseParam); + $resp->assertHeader('donkey', 'cat123'); + } + + public function test_web_middleware_after_return_val_used_as_response() + { + $callback = function () { + return response('cat456', 443); + }; + + Theme::listen(ThemeEvents::WEB_MIDDLEWARE_AFTER, $callback); + + $resp = $this->get('/login', ['Donkey' => 'cat']); + $resp->assertSee('cat456'); + $resp->assertStatus(443); + } + + public function test_auth_login_standard() + { + $args = []; + $callback = function (...$eventArgs) use (&$args) { + $args = $eventArgs; + }; + + Theme::listen(ThemeEvents::AUTH_LOGIN, $callback); + $this->post('/login', ['email' => 'admin@admin.com', 'password' => 'password']); + + $this->assertCount(2, $args); + $this->assertEquals('standard', $args[0]); + $this->assertInstanceOf(User::class, $args[1]); + } + + public function test_auth_register_standard() + { + $args = []; + $callback = function (...$eventArgs) use (&$args) { + $args = $eventArgs; + }; + Theme::listen(ThemeEvents::AUTH_REGISTER, $callback); + $this->setSettings(['registration-enabled' => 'true']); + + $user = User::factory()->make(); + $this->post('/register', ['email' => $user->email, 'name' => $user->name, 'password' => 'password']); + + $this->assertCount(2, $args); + $this->assertEquals('standard', $args[0]); + $this->assertInstanceOf(User::class, $args[1]); + } + + public function test_auth_pre_register() + { + $args = []; + $callback = function (...$eventArgs) use (&$args) { + $args = $eventArgs; + }; + Theme::listen(ThemeEvents::AUTH_PRE_REGISTER, $callback); + $this->setSettings(['registration-enabled' => 'true']); + + $user = User::factory()->make(); + $this->post('/register', ['email' => $user->email, 'name' => $user->name, 'password' => 'password']); + + $this->assertCount(2, $args); + $this->assertEquals('standard', $args[0]); + $this->assertEquals([ + 'email' => $user->email, + 'name' => $user->name, + 'password' => 'password', + ], $args[1]); + $this->assertDatabaseHas('users', ['email' => $user->email]); + } + + public function test_auth_pre_register_with_false_return_blocks_registration() + { + $callback = function () { + return false; + }; + Theme::listen(ThemeEvents::AUTH_PRE_REGISTER, $callback); + $this->setSettings(['registration-enabled' => 'true']); + + $user = User::factory()->make(); + $resp = $this->post('/register', ['email' => $user->email, 'name' => $user->name, 'password' => 'password']); + $resp->assertRedirect('/login'); + $this->assertSessionError('User account could not be registered for the provided details'); + $this->assertDatabaseMissing('users', ['email' => $user->email]); + } + + public function test_webhook_call_before() + { + $args = []; + $callback = function (...$eventArgs) use (&$args) { + $args = $eventArgs; + + return ['test' => 'hello!']; + }; + Theme::listen(ThemeEvents::WEBHOOK_CALL_BEFORE, $callback); + + $responses = $this->mockHttpClient([new \GuzzleHttp\Psr7\Response(200, [], '')]); + + $webhook = new Webhook(['name' => 'Test webhook', 'endpoint' => 'https://example.com']); + $webhook->save(); + $event = ActivityType::PAGE_UPDATE; + $detail = Page::query()->first(); + + dispatch((new DispatchWebhookJob($webhook, $event, $detail))); + + $this->assertCount(5, $args); + $this->assertEquals($event, $args[0]); + $this->assertEquals($webhook->id, $args[1]->id); + $this->assertEquals($detail->id, $args[2]->id); + + $this->assertEquals(1, $responses->requestCount()); + $request = $responses->latestRequest(); + $reqData = json_decode($request->getBody(), true); + $this->assertEquals('hello!', $reqData['test']); + } + + public function test_activity_logged() + { + $book = $this->entities->book(); + $args = []; + $callback = function (...$eventArgs) use (&$args) { + $args = $eventArgs; + }; + + Theme::listen(ThemeEvents::ACTIVITY_LOGGED, $callback); + $this->asEditor()->put($book->getUrl(), ['name' => 'My cool update book!']); + + $this->assertCount(2, $args); + $this->assertEquals(ActivityType::BOOK_UPDATE, $args[0]); + $this->assertTrue($args[1] instanceof Book); + $this->assertEquals($book->id, $args[1]->id); + } + + public function test_page_include_parse() + { + /** @var Page $page */ + /** @var Page $otherPage */ + $page = $this->entities->page(); + $otherPage = Page::query()->where('id', '!=', $page->id)->first(); + $otherPage->html = '

This is a really cool section

'; + $page->html = "

{{@{$otherPage->id}#bkmrk-cool}}

"; + $page->save(); + $otherPage->save(); + + $args = []; + $callback = function (...$eventArgs) use (&$args) { + $args = $eventArgs; + + return 'Big & content replace surprise!'; + }; + + Theme::listen(ThemeEvents::PAGE_INCLUDE_PARSE, $callback); + $resp = $this->asEditor()->get($page->getUrl()); + $this->withHtml($resp)->assertElementContains('.page-content strong', 'Big & content replace surprise!'); + + $this->assertCount(4, $args); + $this->assertEquals($otherPage->id . '#bkmrk-cool', $args[0]); + $this->assertEquals('This is a really cool section', $args[1]); + $this->assertTrue($args[2] instanceof Page); + $this->assertTrue($args[3] instanceof Page); + $this->assertEquals($page->id, $args[2]->id); + $this->assertEquals($otherPage->id, $args[3]->id); + } + + public function test_routes_register_web_and_web_auth() + { + $functionsContent = <<<'END' +get('/cat', fn () => 'cat')->name('say.cat'); +}); +Theme::listen(ThemeEvents::ROUTES_REGISTER_WEB_AUTH, function (Router $router) { + $router->get('/dog', fn () => 'dog')->name('say.dog'); +}); +END; + + $this->usingThemeFolder(function () use ($functionsContent) { + + $functionsFile = theme_path('functions.php'); + file_put_contents($functionsFile, $functionsContent); + + $app = $this->createApplication(); + /** @var \Illuminate\Routing\Router $router */ + $router = $app->get('router'); + + /** @var \Illuminate\Routing\Route $catRoute */ + $catRoute = $router->getRoutes()->getRoutesByName()['say.cat']; + $this->assertEquals(['web'], $catRoute->middleware()); + + /** @var \Illuminate\Routing\Route $dogRoute */ + $dogRoute = $router->getRoutes()->getRoutesByName()['say.dog']; + $this->assertEquals(['web', 'auth'], $dogRoute->middleware()); + }); + } + + public function test_register_views_to_insert_views_before_and_after() + { + $this->usingThemeFolder(function (string $folder) { + $before = 'this-is-my-before-header-string'; + $afterA = 'this-is-my-after-header-string-a'; + $afterB = 'this-is-my-after-header-string-b'; + $afterC = 'this-is-my-after-header-string-{{ 1+51 }}'; + + $functionsContent = <<<'CONTENT' +renderBefore('layouts.parts.header', 'before', 4); + $themeViews->renderAfter('layouts.parts.header', 'after-a', 4); + $themeViews->renderAfter('layouts.parts.header', 'after-b', 1); + $themeViews->renderAfter('layouts.parts.header', 'after-c', 12); +}); +CONTENT; + + $viewDir = theme_path(); + file_put_contents($viewDir . '/functions.php', $functionsContent); + file_put_contents($viewDir . '/before.blade.php', $before); + file_put_contents($viewDir . '/after-a.blade.php', $afterA); + file_put_contents($viewDir . '/after-b.blade.php', $afterB); + file_put_contents($viewDir . '/after-c.blade.php', $afterC); + + $this->refreshApplication(); + $this->artisan('view:clear'); + + $resp = $this->get('/login'); + $resp->assertSee($before); + // Ensure ordering of the multiple after views + $resp->assertSee($afterB . "\n" . $afterA . "\nthis-is-my-after-header-string-52"); + }); + + $this->artisan('view:clear'); + } +} diff --git a/tests/Theme/LogicalThemeTest.php b/tests/Theme/LogicalThemeTest.php new file mode 100644 index 00000000000..feb1c7ea78a --- /dev/null +++ b/tests/Theme/LogicalThemeTest.php @@ -0,0 +1,105 @@ +usingThemeFolder(function ($themeFolder) { + $functionsFile = theme_path('functions.php'); + app()->alias('cat', 'dog'); + file_put_contents($functionsFile, "alias('cat', 'dog');});"); + $this->runWithEnv(['APP_THEME' => $themeFolder], function () { + $this->assertEquals('cat', $this->app->getAlias('dog')); + }); + }); + } + + public function test_theme_functions_loads_errors_are_caught_and_logged() + { + $this->usingThemeFolder(function ($themeFolder) { + $functionsFile = theme_path('functions.php'); + file_put_contents($functionsFile, "expectException(ThemeException::class); + $this->expectExceptionMessageMatches('/Failed loading theme functions file at ".*?" with error: Class "BookStack\\\\Biscuits" not found/'); + + $this->runWithEnv(['APP_THEME' => $themeFolder], fn() => null); + }); + } + + public function test_add_social_driver() + { + Theme::addSocialDriver('catnet', [ + 'client_id' => 'abc123', + 'client_secret' => 'def456', + ], 'SocialiteProviders\Discord\DiscordExtendSocialite@handleTesting'); + + $this->assertEquals('catnet', config('services.catnet.name')); + $this->assertEquals('abc123', config('services.catnet.client_id')); + $this->assertEquals(url('/login/service/catnet/callback'), config('services.catnet.redirect')); + + $loginResp = $this->get('/login'); + $loginResp->assertSee('login/service/catnet'); + } + + public function test_add_social_driver_uses_name_in_config_if_given() + { + Theme::addSocialDriver('catnet', [ + 'client_id' => 'abc123', + 'client_secret' => 'def456', + 'name' => 'Super Cat Name', + ], 'SocialiteProviders\Discord\DiscordExtendSocialite@handleTesting'); + + $this->assertEquals('Super Cat Name', config('services.catnet.name')); + $loginResp = $this->get('/login'); + $loginResp->assertSee('Super Cat Name'); + } + + public function test_add_social_driver_allows_a_configure_for_redirect_callback_to_be_passed() + { + Theme::addSocialDriver( + 'discord', + [ + 'client_id' => 'abc123', + 'client_secret' => 'def456', + 'name' => 'Super Cat Name', + ], + 'SocialiteProviders\Discord\DiscordExtendSocialite@handle', + function ($driver) { + $driver->with(['donkey' => 'donut']); + } + ); + + $loginResp = $this->get('/login/service/discord'); + $redirect = $loginResp->headers->get('location'); + $this->assertStringContainsString('donkey=donut', $redirect); + } + + public function test_register_command_allows_provided_command_to_be_usable_via_artisan() + { + Theme::registerCommand(new MyCustomCommand()); + + Artisan::call('bookstack:test-custom-command', []); + $output = Artisan::output(); + + $this->assertStringContainsString('Command ran!', $output); + } +} + +class MyCustomCommand extends Command +{ + protected $signature = 'bookstack:test-custom-command'; + + public function handle() + { + $this->line('Command ran!'); + } +} diff --git a/tests/Theme/ThemeModuleTests.php b/tests/Theme/ThemeModuleTests.php new file mode 100644 index 00000000000..a7d317dceaf --- /dev/null +++ b/tests/Theme/ThemeModuleTests.php @@ -0,0 +1,223 @@ +usingThemeFolder(function ($themeFolder) { + $a = theme_path('modules/a'); + $b = theme_path('modules/b'); + mkdir($a, 0777, true); + mkdir($b, 0777, true); + + file_put_contents($a . '/bookstack-module.json', json_encode([ + 'name' => 'Module A', + 'description' => 'This is module A', + 'version' => '1.0.0', + ])); + file_put_contents($b . '/bookstack-module.json', json_encode([ + 'name' => 'Module B', + 'description' => 'This is module B', + 'version' => 'v0.5.0', + ])); + + $this->refreshApplication(); + + $modules = Theme::getModules(); + $this->assertCount(2, $modules); + + $moduleA = $modules['a']; + $this->assertEquals('Module A', $moduleA->name); + $this->assertEquals('This is module A', $moduleA->description); + $this->assertEquals('1.0.0', $moduleA->version); + }); + } + + public function test_module_not_loaded_if_no_bookstack_module_json() + { + $this->usingThemeFolder(function ($themeFolder) { + $moduleDir = theme_path('/modules/a'); + mkdir($moduleDir, 0777, true); + file_put_contents($moduleDir . '/module.json', '{}'); + $this->refreshApplication(); + $modules = Theme::getModules(); + $this->assertCount(0, $modules); + }); + } + + public function test_language_text_overridable_via_module() + { + $this->usingModuleFolder(function (string $moduleFolderPath) { + $translationPath = $moduleFolderPath . '/lang/en'; + mkdir($translationPath, 0777, true); + file_put_contents($translationPath . '/entities.php', ' "SuperBeans"];'); + $this->refreshApplication(); + + $this->asAdmin()->get('/books')->assertSee('SuperBeans'); + }); + } + + public function test_language_files_merge_with_theme_files_with_theme_taking_precedence() + { + $this->usingModuleFolder(function (string $moduleFolderPath) { + $moduleTranslationPath = $moduleFolderPath . '/lang/en'; + mkdir($moduleTranslationPath, 0777, true); + file_put_contents($moduleTranslationPath . '/entities.php', ' "SuperBeans", "recently_viewed" => "ViewedBiscuits"];'); + + $themeTranslationPath = theme_path('lang/en'); + mkdir($themeTranslationPath, 0777, true); + file_put_contents($themeTranslationPath . '/entities.php', ' "WonderBeans"];'); + $this->refreshApplication(); + + $this->asAdmin()->get('/books') + ->assertSee('WonderBeans') + ->assertDontSee('SuperBeans') + ->assertSee('ViewedBiscuits'); + }); + } + + public function test_view_files_overridable_from_module() + { + $this->usingModuleFolder(function (string $moduleFolderPath) { + $viewsFolder = $moduleFolderPath . '/views/layouts/parts'; + mkdir($viewsFolder, 0777, true); + file_put_contents($viewsFolder . '/header.blade.php', 'My custom header that says badgerriffic'); + $this->refreshApplication(); + $this->asAdmin()->get('/')->assertSee('badgerriffic'); + }); + } + + public function test_theme_view_files_take_precedence_over_module_view_files() + { + $this->usingModuleFolder(function (string $moduleFolderPath) { + $viewsFolder = $moduleFolderPath . '/views/layouts/parts'; + mkdir($viewsFolder, 0777, true); + file_put_contents($viewsFolder . '/header.blade.php', 'My custom header that says badgerriffic'); + + $themeViewsFolder = theme_path('layouts/parts'); + mkdir($themeViewsFolder, 0777, true); + file_put_contents($themeViewsFolder . '/header.blade.php', 'My theme header that says awesomeferrets'); + + $this->refreshApplication(); + $this->asAdmin()->get('/') + ->assertDontSee('badgerriffic') + ->assertSee('awesomeferrets'); + }); + } + + public function test_theme_and_modules_views_can_be_used_at_the_same_time() + { + $this->usingModuleFolder(function (string $moduleFolderPath) { + $viewsFolder = $moduleFolderPath . '/views/layouts/parts'; + mkdir($viewsFolder, 0777, true); + file_put_contents($viewsFolder . '/base-body-start.blade.php', 'My custom header that says badgerriffic'); + + $themeViewsFolder = theme_path('layouts/parts'); + mkdir($themeViewsFolder, 0777, true); + file_put_contents($themeViewsFolder . '/base-body-end.blade.php', 'My theme header that says awesomeferrets'); + + $this->refreshApplication(); + $this->asAdmin()->get('/') + ->assertSee('badgerriffic') + ->assertSee('awesomeferrets'); + }); + } + + public function test_icons_can_be_overridden_from_module() + { + $this->usingModuleFolder(function (string $moduleFolderPath) { + $iconsFolder = $moduleFolderPath . '/icons'; + mkdir($iconsFolder, 0777, true); + file_put_contents($iconsFolder . '/books.svg', ''); + $this->refreshApplication(); + + $this->asAdmin()->get('/')->assertSee('supericonpath', false); + }); + } + + public function test_theme_icons_take_precedence_over_module_icons() + { + $this->usingModuleFolder(function (string $moduleFolderPath) { + $iconsFolder = $moduleFolderPath . '/icons'; + mkdir($iconsFolder, 0777, true); + file_put_contents($iconsFolder . '/books.svg', ''); + $this->refreshApplication(); + + $themeViewsFolder = theme_path('icons'); + mkdir($themeViewsFolder, 0777, true); + file_put_contents($themeViewsFolder . '/books.svg', ''); + + + $this->asAdmin()->get('/') + ->assertSee('wackyiconpath', false) + ->assertDontSee('supericonpath', false); + }); + } + + public function test_public_folder_can_be_provided_from_module() + { + $this->usingModuleFolder(function (string $moduleFolderPath) { + $publicFolder = $moduleFolderPath . '/public'; + mkdir($publicFolder, 0777, true); + $themeName = basename(dirname(dirname($moduleFolderPath))); + file_put_contents($publicFolder . '/test.txt', 'hellofrominsidethisfileimaghostwoooo!'); + $this->refreshApplication(); + + $resp = $this->asAdmin()->get("/theme/{$themeName}/test.txt")->streamedContent(); + $this->assertEquals('hellofrominsidethisfileimaghostwoooo!', $resp); + }); + } + + public function test_theme_public_files_take_precedence_over_modules() + { + $this->usingModuleFolder(function (string $moduleFolderPath) { + $publicFolder = $moduleFolderPath . '/public'; + mkdir($publicFolder, 0777, true); + $themeName = basename(theme_path()); + file_put_contents($publicFolder . '/test.txt', 'hellofrominsidethisfileimaghostwoooo!'); + + $themePublicFolder = theme_path('public'); + mkdir($themePublicFolder, 0777, true); + file_put_contents($themePublicFolder . '/test.txt', 'imadifferentghostinsidethetheme,woooooo!'); + + $this->refreshApplication(); + + $resp = $this->asAdmin()->get("/theme/{$themeName}/test.txt")->streamedContent(); + $this->assertEquals('imadifferentghostinsidethetheme,woooooo!', $resp); + }); + } + + public function test_logical_functions_file_loaded_from_module_and_it_runs_alongside_theme_functions() + { + $this->usingModuleFolder(function (string $moduleFolderPath) { + file_put_contents($moduleFolderPath . '/functions.php', "alias('cat', 'dog');});"); + + $themeFunctionsFile = theme_path('functions.php'); + file_put_contents($themeFunctionsFile, "alias('beans', 'cheese');});"); + + $this->refreshApplication(); + + $this->assertEquals('cat', $this->app->getAlias('dog')); + $this->assertEquals('beans', $this->app->getAlias('cheese')); + }); + } + + protected function usingModuleFolder(callable $callback): void + { + $this->usingThemeFolder(function (string $themeFolder) use ($callback) { + $moduleFolderPath = theme_path('modules/test-module'); + mkdir($moduleFolderPath, 0777, true); + file_put_contents($moduleFolderPath . '/bookstack-module.json', json_encode([ + 'name' => 'Test Module', + 'description' => 'This is a test module', + 'version' => 'v1.0.0', + ])); + $callback($moduleFolderPath); + }); + } +} diff --git a/tests/Theme/VisualThemeTest.php b/tests/Theme/VisualThemeTest.php new file mode 100644 index 00000000000..c06807d7fd0 --- /dev/null +++ b/tests/Theme/VisualThemeTest.php @@ -0,0 +1,132 @@ +usingThemeFolder(function () { + $translationPath = theme_path('/lang/en'); + File::makeDirectory($translationPath, 0777, true); + + $customTranslations = ' \'Sandwiches\']; + '; + file_put_contents($translationPath . '/entities.php', $customTranslations); + + $homeRequest = $this->actingAs($this->users->viewer())->get('/'); + $this->withHtml($homeRequest)->assertElementContains('header nav', 'Sandwiches'); + }); + } + + public function test_custom_settings_category_page_can_be_added_via_view_file() + { + $content = 'My SuperCustomSettings'; + + $this->usingThemeFolder(function (string $folder) use ($content) { + $viewDir = theme_path('settings/categories'); + mkdir($viewDir, 0777, true); + file_put_contents($viewDir . '/beans.blade.php', $content); + + $this->asAdmin()->get('/settings/beans')->assertSee($content); + }); + } + + public function test_base_body_start_and_end_template_files_can_be_used() + { + $bodyStartStr = 'barry-fought-against-the-panther'; + $bodyEndStr = 'barry-lost-his-fight-with-grace'; + + $this->usingThemeFolder(function (string $folder) use ($bodyStartStr, $bodyEndStr) { + $viewDir = theme_path('layouts/parts'); + mkdir($viewDir, 0777, true); + file_put_contents($viewDir . '/base-body-start.blade.php', $bodyStartStr); + file_put_contents($viewDir . '/base-body-end.blade.php', $bodyEndStr); + + $resp = $this->asEditor()->get('/'); + $resp->assertSee($bodyStartStr); + $resp->assertSee($bodyEndStr); + }); + } + + public function test_export_body_start_and_end_template_files_can_be_used() + { + $bodyStartStr = 'garry-fought-against-the-panther'; + $bodyEndStr = 'garry-lost-his-fight-with-grace'; + $page = $this->entities->page(); + + $this->usingThemeFolder(function (string $folder) use ($bodyStartStr, $bodyEndStr, $page) { + $viewDir = theme_path('layouts/parts'); + mkdir($viewDir, 0777, true); + file_put_contents($viewDir . '/export-body-start.blade.php', $bodyStartStr); + file_put_contents($viewDir . '/export-body-end.blade.php', $bodyEndStr); + + $resp = $this->asEditor()->get($page->getUrl('/export/html')); + $resp->assertSee($bodyStartStr); + $resp->assertSee($bodyEndStr); + }); + } + + public function test_login_and_register_message_template_files_can_be_used() + { + $loginMessage = 'Welcome to this instance, login below you scallywag'; + $registerMessage = 'You want to register? Enter the deets below you numpty'; + + $this->usingThemeFolder(function (string $folder) use ($loginMessage, $registerMessage) { + $viewDir = theme_path('auth/parts'); + mkdir($viewDir, 0777, true); + file_put_contents($viewDir . '/login-message.blade.php', $loginMessage); + file_put_contents($viewDir . '/register-message.blade.php', $registerMessage); + $this->setSettings(['registration-enabled' => 'true']); + + $this->get('/login')->assertSee($loginMessage); + $this->get('/register')->assertSee($registerMessage); + }); + } + + public function test_header_links_start_template_file_can_be_used() + { + $content = 'This is added text in the header bar'; + + $this->usingThemeFolder(function (string $folder) use ($content) { + $viewDir = theme_path('layouts/parts'); + mkdir($viewDir, 0777, true); + file_put_contents($viewDir . '/header-links-start.blade.php', $content); + $this->setSettings(['registration-enabled' => 'true']); + + $this->get('/login')->assertSee($content); + }); + } + + public function test_public_folder_contents_accessible_via_route() + { + $this->usingThemeFolder(function (string $themeFolderName) { + $publicDir = theme_path('public'); + mkdir($publicDir, 0777, true); + + $text = 'some-text ' . md5(random_bytes(5)); + $css = "body { background-color: tomato !important; }"; + file_put_contents("{$publicDir}/file.txt", $text); + file_put_contents("{$publicDir}/file.css", $css); + copy($this->files->testFilePath('test-image.png'), "{$publicDir}/image.png"); + + $resp = $this->asAdmin()->get("/theme/{$themeFolderName}/file.txt"); + $resp->assertStreamedContent($text); + $resp->assertHeader('Content-Type', 'text/plain; charset=utf-8'); + $resp->assertHeader('Cache-Control', 'max-age=86400, private'); + + $resp = $this->asAdmin()->get("/theme/{$themeFolderName}/image.png"); + $resp->assertHeader('Content-Type', 'image/png'); + $resp->assertHeader('Cache-Control', 'max-age=86400, private'); + + $resp = $this->asAdmin()->get("/theme/{$themeFolderName}/file.css"); + $resp->assertStreamedContent($css); + $resp->assertHeader('Content-Type', 'text/css; charset=utf-8'); + $resp->assertHeader('Cache-Control', 'max-age=86400, private'); + }); + } +} diff --git a/tests/ThemeTest.php b/tests/ThemeTest.php deleted file mode 100644 index 841ff78caf0..00000000000 --- a/tests/ThemeTest.php +++ /dev/null @@ -1,521 +0,0 @@ -usingThemeFolder(function () { - $translationPath = theme_path('/lang/en'); - File::makeDirectory($translationPath, 0777, true); - - $customTranslations = ' \'Sandwiches\']; - '; - file_put_contents($translationPath . '/entities.php', $customTranslations); - - $homeRequest = $this->actingAs($this->users->viewer())->get('/'); - $this->withHtml($homeRequest)->assertElementContains('header nav', 'Sandwiches'); - }); - } - - public function test_theme_functions_file_used_and_app_boot_event_runs() - { - $this->usingThemeFolder(function ($themeFolder) { - $functionsFile = theme_path('functions.php'); - app()->alias('cat', 'dog'); - file_put_contents($functionsFile, "alias('cat', 'dog');});"); - $this->runWithEnv(['APP_THEME' => $themeFolder], function () { - $this->assertEquals('cat', $this->app->getAlias('dog')); - }); - }); - } - - public function test_theme_functions_loads_errors_are_caught_and_logged() - { - $this->usingThemeFolder(function ($themeFolder) { - $functionsFile = theme_path('functions.php'); - file_put_contents($functionsFile, "expectException(ThemeException::class); - $this->expectExceptionMessageMatches('/Failed loading theme functions file at ".*?" with error: Class "BookStack\\\\Biscuits" not found/'); - - $this->runWithEnv(['APP_THEME' => $themeFolder], fn() => null); - }); - } - - public function test_event_commonmark_environment_configure() - { - $callbackCalled = false; - $callback = function ($environment) use (&$callbackCalled) { - $this->assertInstanceOf(Environment::class, $environment); - $callbackCalled = true; - - return $environment; - }; - Theme::listen(ThemeEvents::COMMONMARK_ENVIRONMENT_CONFIGURE, $callback); - - $page = $this->entities->page(); - $content = new PageContent($page); - $content->setNewMarkdown('# test', $this->users->editor()); - - $this->assertTrue($callbackCalled); - } - - public function test_event_web_middleware_before() - { - $callbackCalled = false; - $requestParam = null; - $callback = function ($request) use (&$callbackCalled, &$requestParam) { - $requestParam = $request; - $callbackCalled = true; - }; - - Theme::listen(ThemeEvents::WEB_MIDDLEWARE_BEFORE, $callback); - $this->get('/login', ['Donkey' => 'cat']); - - $this->assertTrue($callbackCalled); - $this->assertInstanceOf(Request::class, $requestParam); - $this->assertEquals('cat', $requestParam->header('donkey')); - } - - public function test_event_web_middleware_before_return_val_used_as_response() - { - $callback = function (Request $request) { - return response('cat', 412); - }; - - Theme::listen(ThemeEvents::WEB_MIDDLEWARE_BEFORE, $callback); - $resp = $this->get('/login', ['Donkey' => 'cat']); - $resp->assertSee('cat'); - $resp->assertStatus(412); - } - - public function test_event_web_middleware_after() - { - $callbackCalled = false; - $requestParam = null; - $responseParam = null; - $callback = function ($request, Response $response) use (&$callbackCalled, &$requestParam, &$responseParam) { - $requestParam = $request; - $responseParam = $response; - $callbackCalled = true; - $response->header('donkey', 'cat123'); - }; - - Theme::listen(ThemeEvents::WEB_MIDDLEWARE_AFTER, $callback); - - $resp = $this->get('/login', ['Donkey' => 'cat']); - $this->assertTrue($callbackCalled); - $this->assertInstanceOf(Request::class, $requestParam); - $this->assertInstanceOf(Response::class, $responseParam); - $resp->assertHeader('donkey', 'cat123'); - } - - public function test_event_web_middleware_after_return_val_used_as_response() - { - $callback = function () { - return response('cat456', 443); - }; - - Theme::listen(ThemeEvents::WEB_MIDDLEWARE_AFTER, $callback); - - $resp = $this->get('/login', ['Donkey' => 'cat']); - $resp->assertSee('cat456'); - $resp->assertStatus(443); - } - - public function test_event_auth_login_standard() - { - $args = []; - $callback = function (...$eventArgs) use (&$args) { - $args = $eventArgs; - }; - - Theme::listen(ThemeEvents::AUTH_LOGIN, $callback); - $this->post('/login', ['email' => 'admin@admin.com', 'password' => 'password']); - - $this->assertCount(2, $args); - $this->assertEquals('standard', $args[0]); - $this->assertInstanceOf(User::class, $args[1]); - } - - public function test_event_auth_register_standard() - { - $args = []; - $callback = function (...$eventArgs) use (&$args) { - $args = $eventArgs; - }; - Theme::listen(ThemeEvents::AUTH_REGISTER, $callback); - $this->setSettings(['registration-enabled' => 'true']); - - $user = User::factory()->make(); - $this->post('/register', ['email' => $user->email, 'name' => $user->name, 'password' => 'password']); - - $this->assertCount(2, $args); - $this->assertEquals('standard', $args[0]); - $this->assertInstanceOf(User::class, $args[1]); - } - - public function test_event_auth_pre_register() - { - $args = []; - $callback = function (...$eventArgs) use (&$args) { - $args = $eventArgs; - }; - Theme::listen(ThemeEvents::AUTH_PRE_REGISTER, $callback); - $this->setSettings(['registration-enabled' => 'true']); - - $user = User::factory()->make(); - $this->post('/register', ['email' => $user->email, 'name' => $user->name, 'password' => 'password']); - - $this->assertCount(2, $args); - $this->assertEquals('standard', $args[0]); - $this->assertEquals([ - 'email' => $user->email, - 'name' => $user->name, - 'password' => 'password', - ], $args[1]); - $this->assertDatabaseHas('users', ['email' => $user->email]); - } - - public function test_event_auth_pre_register_with_false_return_blocks_registration() - { - $callback = function () { - return false; - }; - Theme::listen(ThemeEvents::AUTH_PRE_REGISTER, $callback); - $this->setSettings(['registration-enabled' => 'true']); - - $user = User::factory()->make(); - $resp = $this->post('/register', ['email' => $user->email, 'name' => $user->name, 'password' => 'password']); - $resp->assertRedirect('/login'); - $this->assertSessionError('User account could not be registered for the provided details'); - $this->assertDatabaseMissing('users', ['email' => $user->email]); - } - - public function test_event_webhook_call_before() - { - $args = []; - $callback = function (...$eventArgs) use (&$args) { - $args = $eventArgs; - - return ['test' => 'hello!']; - }; - Theme::listen(ThemeEvents::WEBHOOK_CALL_BEFORE, $callback); - - $responses = $this->mockHttpClient([new \GuzzleHttp\Psr7\Response(200, [], '')]); - - $webhook = new Webhook(['name' => 'Test webhook', 'endpoint' => 'https://example.com']); - $webhook->save(); - $event = ActivityType::PAGE_UPDATE; - $detail = Page::query()->first(); - - dispatch((new DispatchWebhookJob($webhook, $event, $detail))); - - $this->assertCount(5, $args); - $this->assertEquals($event, $args[0]); - $this->assertEquals($webhook->id, $args[1]->id); - $this->assertEquals($detail->id, $args[2]->id); - - $this->assertEquals(1, $responses->requestCount()); - $request = $responses->latestRequest(); - $reqData = json_decode($request->getBody(), true); - $this->assertEquals('hello!', $reqData['test']); - } - - public function test_event_activity_logged() - { - $book = $this->entities->book(); - $args = []; - $callback = function (...$eventArgs) use (&$args) { - $args = $eventArgs; - }; - - Theme::listen(ThemeEvents::ACTIVITY_LOGGED, $callback); - $this->asEditor()->put($book->getUrl(), ['name' => 'My cool update book!']); - - $this->assertCount(2, $args); - $this->assertEquals(ActivityType::BOOK_UPDATE, $args[0]); - $this->assertTrue($args[1] instanceof Book); - $this->assertEquals($book->id, $args[1]->id); - } - - public function test_event_page_include_parse() - { - /** @var Page $page */ - /** @var Page $otherPage */ - $page = $this->entities->page(); - $otherPage = Page::query()->where('id', '!=', $page->id)->first(); - $otherPage->html = '

This is a really cool section

'; - $page->html = "

{{@{$otherPage->id}#bkmrk-cool}}

"; - $page->save(); - $otherPage->save(); - - $args = []; - $callback = function (...$eventArgs) use (&$args) { - $args = $eventArgs; - - return 'Big & content replace surprise!'; - }; - - Theme::listen(ThemeEvents::PAGE_INCLUDE_PARSE, $callback); - $resp = $this->asEditor()->get($page->getUrl()); - $this->withHtml($resp)->assertElementContains('.page-content strong', 'Big & content replace surprise!'); - - $this->assertCount(4, $args); - $this->assertEquals($otherPage->id . '#bkmrk-cool', $args[0]); - $this->assertEquals('This is a really cool section', $args[1]); - $this->assertTrue($args[2] instanceof Page); - $this->assertTrue($args[3] instanceof Page); - $this->assertEquals($page->id, $args[2]->id); - $this->assertEquals($otherPage->id, $args[3]->id); - } - - public function test_event_routes_register_web_and_web_auth() - { - $functionsContent = <<<'END' -get('/cat', fn () => 'cat')->name('say.cat'); -}); -Theme::listen(ThemeEvents::ROUTES_REGISTER_WEB_AUTH, function (Router $router) { - $router->get('/dog', fn () => 'dog')->name('say.dog'); -}); -END; - - $this->usingThemeFolder(function () use ($functionsContent) { - - $functionsFile = theme_path('functions.php'); - file_put_contents($functionsFile, $functionsContent); - - $app = $this->createApplication(); - /** @var \Illuminate\Routing\Router $router */ - $router = $app->get('router'); - - /** @var \Illuminate\Routing\Route $catRoute */ - $catRoute = $router->getRoutes()->getRoutesByName()['say.cat']; - $this->assertEquals(['web'], $catRoute->middleware()); - - /** @var \Illuminate\Routing\Route $dogRoute */ - $dogRoute = $router->getRoutes()->getRoutesByName()['say.dog']; - $this->assertEquals(['web', 'auth'], $dogRoute->middleware()); - }); - } - - public function test_add_social_driver() - { - Theme::addSocialDriver('catnet', [ - 'client_id' => 'abc123', - 'client_secret' => 'def456', - ], 'SocialiteProviders\Discord\DiscordExtendSocialite@handleTesting'); - - $this->assertEquals('catnet', config('services.catnet.name')); - $this->assertEquals('abc123', config('services.catnet.client_id')); - $this->assertEquals(url('/login/service/catnet/callback'), config('services.catnet.redirect')); - - $loginResp = $this->get('/login'); - $loginResp->assertSee('login/service/catnet'); - } - - public function test_add_social_driver_uses_name_in_config_if_given() - { - Theme::addSocialDriver('catnet', [ - 'client_id' => 'abc123', - 'client_secret' => 'def456', - 'name' => 'Super Cat Name', - ], 'SocialiteProviders\Discord\DiscordExtendSocialite@handleTesting'); - - $this->assertEquals('Super Cat Name', config('services.catnet.name')); - $loginResp = $this->get('/login'); - $loginResp->assertSee('Super Cat Name'); - } - - public function test_add_social_driver_allows_a_configure_for_redirect_callback_to_be_passed() - { - Theme::addSocialDriver( - 'discord', - [ - 'client_id' => 'abc123', - 'client_secret' => 'def456', - 'name' => 'Super Cat Name', - ], - 'SocialiteProviders\Discord\DiscordExtendSocialite@handle', - function ($driver) { - $driver->with(['donkey' => 'donut']); - } - ); - - $loginResp = $this->get('/login/service/discord'); - $redirect = $loginResp->headers->get('location'); - $this->assertStringContainsString('donkey=donut', $redirect); - } - - public function test_register_command_allows_provided_command_to_be_usable_via_artisan() - { - Theme::registerCommand(new MyCustomCommand()); - - Artisan::call('bookstack:test-custom-command', []); - $output = Artisan::output(); - - $this->assertStringContainsString('Command ran!', $output); - } - - public function test_base_body_start_and_end_template_files_can_be_used() - { - $bodyStartStr = 'barry-fought-against-the-panther'; - $bodyEndStr = 'barry-lost-his-fight-with-grace'; - - $this->usingThemeFolder(function (string $folder) use ($bodyStartStr, $bodyEndStr) { - $viewDir = theme_path('layouts/parts'); - mkdir($viewDir, 0777, true); - file_put_contents($viewDir . '/base-body-start.blade.php', $bodyStartStr); - file_put_contents($viewDir . '/base-body-end.blade.php', $bodyEndStr); - - $resp = $this->asEditor()->get('/'); - $resp->assertSee($bodyStartStr); - $resp->assertSee($bodyEndStr); - }); - } - - public function test_export_body_start_and_end_template_files_can_be_used() - { - $bodyStartStr = 'garry-fought-against-the-panther'; - $bodyEndStr = 'garry-lost-his-fight-with-grace'; - $page = $this->entities->page(); - - $this->usingThemeFolder(function (string $folder) use ($bodyStartStr, $bodyEndStr, $page) { - $viewDir = theme_path('layouts/parts'); - mkdir($viewDir, 0777, true); - file_put_contents($viewDir . '/export-body-start.blade.php', $bodyStartStr); - file_put_contents($viewDir . '/export-body-end.blade.php', $bodyEndStr); - - $resp = $this->asEditor()->get($page->getUrl('/export/html')); - $resp->assertSee($bodyStartStr); - $resp->assertSee($bodyEndStr); - }); - } - - public function test_login_and_register_message_template_files_can_be_used() - { - $loginMessage = 'Welcome to this instance, login below you scallywag'; - $registerMessage = 'You want to register? Enter the deets below you numpty'; - - $this->usingThemeFolder(function (string $folder) use ($loginMessage, $registerMessage) { - $viewDir = theme_path('auth/parts'); - mkdir($viewDir, 0777, true); - file_put_contents($viewDir . '/login-message.blade.php', $loginMessage); - file_put_contents($viewDir . '/register-message.blade.php', $registerMessage); - $this->setSettings(['registration-enabled' => 'true']); - - $this->get('/login')->assertSee($loginMessage); - $this->get('/register')->assertSee($registerMessage); - }); - } - - public function test_header_links_start_template_file_can_be_used() - { - $content = 'This is added text in the header bar'; - - $this->usingThemeFolder(function (string $folder) use ($content) { - $viewDir = theme_path('layouts/parts'); - mkdir($viewDir, 0777, true); - file_put_contents($viewDir . '/header-links-start.blade.php', $content); - $this->setSettings(['registration-enabled' => 'true']); - - $this->get('/login')->assertSee($content); - }); - } - - public function test_custom_settings_category_page_can_be_added_via_view_file() - { - $content = 'My SuperCustomSettings'; - - $this->usingThemeFolder(function (string $folder) use ($content) { - $viewDir = theme_path('settings/categories'); - mkdir($viewDir, 0777, true); - file_put_contents($viewDir . '/beans.blade.php', $content); - - $this->asAdmin()->get('/settings/beans')->assertSee($content); - }); - } - - public function test_public_folder_contents_accessible_via_route() - { - $this->usingThemeFolder(function (string $themeFolderName) { - $publicDir = theme_path('public'); - mkdir($publicDir, 0777, true); - - $text = 'some-text ' . md5(random_bytes(5)); - $css = "body { background-color: tomato !important; }"; - file_put_contents("{$publicDir}/file.txt", $text); - file_put_contents("{$publicDir}/file.css", $css); - copy($this->files->testFilePath('test-image.png'), "{$publicDir}/image.png"); - - $resp = $this->asAdmin()->get("/theme/{$themeFolderName}/file.txt"); - $resp->assertStreamedContent($text); - $resp->assertHeader('Content-Type', 'text/plain; charset=utf-8'); - $resp->assertHeader('Cache-Control', 'max-age=86400, private'); - - $resp = $this->asAdmin()->get("/theme/{$themeFolderName}/image.png"); - $resp->assertHeader('Content-Type', 'image/png'); - $resp->assertHeader('Cache-Control', 'max-age=86400, private'); - - $resp = $this->asAdmin()->get("/theme/{$themeFolderName}/file.css"); - $resp->assertStreamedContent($css); - $resp->assertHeader('Content-Type', 'text/css; charset=utf-8'); - $resp->assertHeader('Cache-Control', 'max-age=86400, private'); - }); - } - - protected function usingThemeFolder(callable $callback) - { - // Create a folder and configure a theme - $themeFolderName = 'testing_theme_' . str_shuffle(rtrim(base64_encode(time()), '=')); - config()->set('view.theme', $themeFolderName); - $themeFolderPath = theme_path(''); - - // Create theme folder and clean it up on application tear-down - File::makeDirectory($themeFolderPath); - $this->beforeApplicationDestroyed(fn() => File::deleteDirectory($themeFolderPath)); - - // Run provided callback with theme env option set - $this->runWithEnv(['APP_THEME' => $themeFolderName], function () use ($callback, $themeFolderName) { - call_user_func($callback, $themeFolderName); - }); - } -} - -class MyCustomCommand extends Command -{ - protected $signature = 'bookstack:test-custom-command'; - - public function handle() - { - $this->line('Command ran!'); - } -}