From 36649a618858e0309fce0f1d5ce90bfaf47c4605 Mon Sep 17 00:00:00 2001 From: Dan Brown Date: Mon, 26 Jan 2026 11:55:39 +0000 Subject: [PATCH 1/8] Theme: Updated view registration to be dynamic Within the responsibility of the theme service instead of being part of the app configuration. --- app/App/Providers/ThemeServiceProvider.php | 1 + app/Config/view.php | 8 +------- app/Theming/ThemeService.php | 10 ++++++++++ 3 files changed, 12 insertions(+), 7 deletions(-) diff --git a/app/App/Providers/ThemeServiceProvider.php b/app/App/Providers/ThemeServiceProvider.php index 2cf581d3863..a806c1df622 100644 --- a/app/App/Providers/ThemeServiceProvider.php +++ b/app/App/Providers/ThemeServiceProvider.php @@ -24,6 +24,7 @@ public function boot(): void { // Boot up the theme system $themeService = $this->app->make(ThemeService::class); + $themeService->registerViewPathsForTheme($this->app->make('view')->getFinder()); $themeService->readThemeActions(); $themeService->dispatch(ThemeEvents::APP_BOOT, $this->app); } 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/ThemeService.php b/app/Theming/ThemeService.php index 4bdb6836b02..87811f0efd1 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 @@ -90,6 +91,15 @@ public function readThemeActions(): void } } + /** + * Register any extra paths for where we may expect views to be located + * with the provided FileViewFinder, to make custom views available for use. + */ + public function registerViewPathsForTheme(FileViewFinder $finder): void + { + $finder->prependLocation(theme_path()); + } + /** * @see SocialDriverManager::addSocialDriver */ From c32b1686a95e17ab143faac1eb6b1611fe0e5286 Mon Sep 17 00:00:00 2001 From: Dan Brown Date: Mon, 26 Jan 2026 17:16:14 +0000 Subject: [PATCH 2/8] Theme: Added the ability to add views before/after existing ones Adds a registration system via the logical theme system, to tell BookStack about views to render before or after a specific template is included in the system. --- app/App/Providers/ThemeServiceProvider.php | 17 ++++- app/Theming/ThemeService.php | 88 ++++++++++++++++++++-- 2 files changed, 96 insertions(+), 9 deletions(-) diff --git a/app/App/Providers/ThemeServiceProvider.php b/app/App/Providers/ThemeServiceProvider.php index a806c1df622..98ad509f355 100644 --- a/app/App/Providers/ThemeServiceProvider.php +++ b/app/App/Providers/ThemeServiceProvider.php @@ -4,7 +4,9 @@ use BookStack\Theming\ThemeEvents; use BookStack\Theming\ThemeService; +use Illuminate\Support\Facades\Blade; use Illuminate\Support\ServiceProvider; +use Illuminate\View\View; class ThemeServiceProvider extends ServiceProvider { @@ -24,8 +26,17 @@ public function boot(): void { // Boot up the theme system $themeService = $this->app->make(ThemeService::class); - $themeService->registerViewPathsForTheme($this->app->make('view')->getFinder()); - $themeService->readThemeActions(); - $themeService->dispatch(ThemeEvents::APP_BOOT, $this->app); + + $viewFactory = $this->app->make('view'); + $themeService->registerViewPathsForTheme($viewFactory->getFinder()); + + if ($themeService->logicalThemeIsActive()) { + $themeService->readThemeActions(); + $themeService->dispatch(ThemeEvents::APP_BOOT, $this->app); + $viewFactory->share('__theme', $themeService); + Blade::directive('include', function ($expression) { + return "handleViewInclude({$expression}, array_diff_key(get_defined_vars(), ['__data' => 1, '__path' => 1])); ?>"; + }); + } } } diff --git a/app/Theming/ThemeService.php b/app/Theming/ThemeService.php index 87811f0efd1..9587ceccb3f 100644 --- a/app/Theming/ThemeService.php +++ b/app/Theming/ThemeService.php @@ -16,6 +16,16 @@ class ThemeService */ protected array $listeners = []; + /** + * @var array> + */ + protected array $beforeViews = []; + + /** + * @var array> + */ + protected array $afterViews = []; + /** * Get the currently configured theme. * Returns an empty string if not configured. @@ -82,15 +92,22 @@ public function registerCommand(Command $command): void public function readThemeActions(): void { $themeActionsFile = theme_path('functions.php'); - if ($themeActionsFile && file_exists($themeActionsFile)) { - try { - require $themeActionsFile; - } catch (\Error $exception) { - throw new ThemeException("Failed loading theme functions file at \"{$themeActionsFile}\" with error: {$exception->getMessage()}"); - } + try { + require $themeActionsFile; + } catch (\Error $exception) { + throw new ThemeException("Failed loading theme functions file at \"{$themeActionsFile}\" with error: {$exception->getMessage()}"); } } + /** + * Check if a logical theme is active. + */ + public function logicalThemeIsActive(): bool + { + $themeActionsFile = theme_path('functions.php'); + return $themeActionsFile && file_exists($themeActionsFile); + } + /** * Register any extra paths for where we may expect views to be located * with the provided FileViewFinder, to make custom views available for use. @@ -108,4 +125,63 @@ public function addSocialDriver(string $driverName, array $config, string $socia $driverManager = app()->make(SocialDriverManager::class); $driverManager->addSocialDriver($driverName, $config, $socialiteHandler, $configureForRedirect); } + + /** + * Provide the response for a blade template view include. + */ + public function handleViewInclude(string $viewPath, array $data = []): string + { + $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 registerViewRenderBefore(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 registerViewRenderAfter(string $targetView, string $localView, int $priority = 50): void + { + $this->registerAdjacentView($this->afterViews, $targetView, $localView, $priority); + } + + 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); + } } From 9fcfc762ec9bf36b173a002fccbc702eeba410b3 Mon Sep 17 00:00:00 2001 From: Dan Brown Date: Tue, 27 Jan 2026 00:36:35 +0000 Subject: [PATCH 3/8] Theme: Added testing of registerViewToRender* functions Updated function name also. --- app/App/helpers.php | 3 +-- app/Theming/ThemeService.php | 4 ++-- tests/ThemeTest.php | 32 ++++++++++++++++++++++++++++++++ 3 files changed, 35 insertions(+), 4 deletions(-) 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/Theming/ThemeService.php b/app/Theming/ThemeService.php index 9587ceccb3f..0a6327af85a 100644 --- a/app/Theming/ThemeService.php +++ b/app/Theming/ThemeService.php @@ -143,7 +143,7 @@ public function handleViewInclude(string $viewPath, array $data = []): string /** * Register a custom view to be rendered before the given target view is included in the template system. */ - public function registerViewRenderBefore(string $targetView, string $localView, int $priority = 50): void + public function registerViewToRenderBefore(string $targetView, string $localView, int $priority = 50): void { $this->registerAdjacentView($this->beforeViews, $targetView, $localView, $priority); } @@ -151,7 +151,7 @@ public function registerViewRenderBefore(string $targetView, string $localView, /** * Register a custom view to be rendered after the given target view is included in the template system. */ - public function registerViewRenderAfter(string $targetView, string $localView, int $priority = 50): void + public function registerViewToRenderAfter(string $targetView, string $localView, int $priority = 50): void { $this->registerAdjacentView($this->afterViews, $targetView, $localView, $priority); } diff --git a/tests/ThemeTest.php b/tests/ThemeTest.php index 841ff78caf0..014f3a92f18 100644 --- a/tests/ThemeTest.php +++ b/tests/ThemeTest.php @@ -492,6 +492,38 @@ public function test_public_folder_contents_accessible_via_route() }); } + public function test_register_view_to_render_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' +refreshApplication(); + + $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"); + }); + } + protected function usingThemeFolder(callable $callback) { // Create a folder and configure a theme From 1b17bb3929d35410bfb5ed80f15bad911f84e832 Mon Sep 17 00:00:00 2001 From: Dan Brown Date: Tue, 27 Jan 2026 16:50:50 +0000 Subject: [PATCH 4/8] Theme: Changed how before/after views are registered Changed the system out to be a theme event instead of method, to align with other registration events, and so that the theme view work can better be contained in its own class. --- app/App/Providers/ThemeServiceProvider.php | 21 +++-- app/Theming/ThemeEvents.php | 10 +++ app/Theming/ThemeService.php | 91 +------------------- app/Theming/ThemeViews.php | 96 ++++++++++++++++++++++ tests/ThemeTest.php | 17 ++-- 5 files changed, 135 insertions(+), 100 deletions(-) create mode 100644 app/Theming/ThemeViews.php diff --git a/app/App/Providers/ThemeServiceProvider.php b/app/App/Providers/ThemeServiceProvider.php index 98ad509f355..e32f90b9afe 100644 --- a/app/App/Providers/ThemeServiceProvider.php +++ b/app/App/Providers/ThemeServiceProvider.php @@ -4,9 +4,9 @@ use BookStack\Theming\ThemeEvents; use BookStack\Theming\ThemeService; +use BookStack\Theming\ThemeViews; use Illuminate\Support\Facades\Blade; use Illuminate\Support\ServiceProvider; -use Illuminate\View\View; class ThemeServiceProvider extends ServiceProvider { @@ -26,16 +26,21 @@ public function boot(): void { // Boot up the theme system $themeService = $this->app->make(ThemeService::class); - $viewFactory = $this->app->make('view'); - $themeService->registerViewPathsForTheme($viewFactory->getFinder()); + if (!$themeService->getTheme()) { + return; + } + + $themeService->readThemeActions(); + $themeService->dispatch(ThemeEvents::APP_BOOT, $this->app); - if ($themeService->logicalThemeIsActive()) { - $themeService->readThemeActions(); - $themeService->dispatch(ThemeEvents::APP_BOOT, $this->app); - $viewFactory->share('__theme', $themeService); + $themeViews = new ThemeViews(); + $themeService->dispatch(ThemeEvents::THEME_REGISTER_VIEWS, $themeViews); + $themeViews->registerViewPathsForTheme($viewFactory->getFinder()); + 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])); ?>"; + return "handleViewInclude({$expression}, array_diff_key(get_defined_vars(), ['__data' => 1, '__path' => 1])); ?>"; }); } } 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/ThemeService.php b/app/Theming/ThemeService.php index 0a6327af85a..14281adca30 100644 --- a/app/Theming/ThemeService.php +++ b/app/Theming/ThemeService.php @@ -16,16 +16,6 @@ class ThemeService */ protected array $listeners = []; - /** - * @var array> - */ - protected array $beforeViews = []; - - /** - * @var array> - */ - protected array $afterViews = []; - /** * Get the currently configured theme. * Returns an empty string if not configured. @@ -92,6 +82,10 @@ public function registerCommand(Command $command): void public function readThemeActions(): void { $themeActionsFile = theme_path('functions.php'); + if (!$themeActionsFile || !file_exists($themeActionsFile)) { + return; + } + try { require $themeActionsFile; } catch (\Error $exception) { @@ -99,24 +93,6 @@ public function readThemeActions(): void } } - /** - * Check if a logical theme is active. - */ - public function logicalThemeIsActive(): bool - { - $themeActionsFile = theme_path('functions.php'); - return $themeActionsFile && file_exists($themeActionsFile); - } - - /** - * Register any extra paths for where we may expect views to be located - * with the provided FileViewFinder, to make custom views available for use. - */ - public function registerViewPathsForTheme(FileViewFinder $finder): void - { - $finder->prependLocation(theme_path()); - } - /** * @see SocialDriverManager::addSocialDriver */ @@ -125,63 +101,4 @@ public function addSocialDriver(string $driverName, array $config, string $socia $driverManager = app()->make(SocialDriverManager::class); $driverManager->addSocialDriver($driverName, $config, $socialiteHandler, $configureForRedirect); } - - /** - * Provide the response for a blade template view include. - */ - public function handleViewInclude(string $viewPath, array $data = []): string - { - $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 registerViewToRenderBefore(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 registerViewToRenderAfter(string $targetView, string $localView, int $priority = 50): void - { - $this->registerAdjacentView($this->afterViews, $targetView, $localView, $priority); - } - - 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/Theming/ThemeViews.php b/app/Theming/ThemeViews.php new file mode 100644 index 00000000000..719f8e3ce24 --- /dev/null +++ b/app/Theming/ThemeViews.php @@ -0,0 +1,96 @@ +> + */ + 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. + */ + public function registerViewPathsForTheme(FileViewFinder $finder): void + { + $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/tests/ThemeTest.php b/tests/ThemeTest.php index 014f3a92f18..f640513cf1d 100644 --- a/tests/ThemeTest.php +++ b/tests/ThemeTest.php @@ -492,7 +492,7 @@ public function test_public_folder_contents_accessible_via_route() }); } - public function test_register_view_to_render_before_and_after() + public function test_theme_register_views_event_to_insert_views_before_and_after() { $this->usingThemeFolder(function (string $folder) { $before = 'this-is-my-before-header-string'; @@ -502,10 +502,14 @@ public function test_register_view_to_render_before_and_after() $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(); @@ -516,12 +520,15 @@ public function test_register_view_to_render_before_and_after() 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'); } protected function usingThemeFolder(callable $callback) From 4949520194a8397497e15155e90c46de46693bde Mon Sep 17 00:00:00 2001 From: Dan Brown Date: Sun, 1 Feb 2026 11:53:46 +0000 Subject: [PATCH 5/8] Theme System: Added initial module implementations --- app/App/Providers/ThemeServiceProvider.php | 3 +- app/Theming/ThemeController.php | 7 +- app/Theming/ThemeModule.php | 50 ++++++++++++ app/Theming/ThemeService.php | 93 ++++++++++++++++++++-- app/Theming/ThemeViews.php | 10 ++- app/Translation/FileLoader.php | 19 +++-- app/Util/SvgIcon.php | 11 ++- 7 files changed, 168 insertions(+), 25 deletions(-) create mode 100644 app/Theming/ThemeModule.php diff --git a/app/App/Providers/ThemeServiceProvider.php b/app/App/Providers/ThemeServiceProvider.php index e32f90b9afe..50c76bbf846 100644 --- a/app/App/Providers/ThemeServiceProvider.php +++ b/app/App/Providers/ThemeServiceProvider.php @@ -31,12 +31,13 @@ public function boot(): void 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()); + $themeViews->registerViewPathsForTheme($viewFactory->getFinder(), $themeService->getModules()); if ($themeViews->hasRegisteredViews()) { $viewFactory->share('__themeViews', $themeViews); Blade::directive('include', function ($expression) { 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/ThemeModule.php b/app/Theming/ThemeModule.php new file mode 100644 index 00000000000..9bbc0103ae5 --- /dev/null +++ b/app/Theming/ThemeModule.php @@ -0,0 +1,50 @@ +name = $data['name']; + $module->description = $data['description']; + $module->folderName = $folderName; + $module->version = $data['version']; + + return $module; + } + + /** + * Get a path for a file within this module. + */ + public function path($path = ''): string + { + $component = trim($path, '/'); + return theme_path("modules/{$this->folderName}/{$component}"); + } +} diff --git a/app/Theming/ThemeService.php b/app/Theming/ThemeService.php index 14281adca30..6f31129804c 100644 --- a/app/Theming/ThemeService.php +++ b/app/Theming/ThemeService.php @@ -16,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. @@ -77,20 +82,94 @@ 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 $functionFile; + } catch (\Error $exception) { + 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; } - try { - require $themeActionsFile; - } catch (\Error $exception) { - throw new ThemeException("Failed loading theme functions file at \"{$themeActionsFile}\" with error: {$exception->getMessage()}"); + $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; } /** diff --git a/app/Theming/ThemeViews.php b/app/Theming/ThemeViews.php index 719f8e3ce24..b2d0adc02f6 100644 --- a/app/Theming/ThemeViews.php +++ b/app/Theming/ThemeViews.php @@ -20,9 +20,17 @@ class ThemeViews /** * 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): void + 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()); } 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 ''; } From cd84074cdf80242fe177fe8b16401bb14e46a7ce Mon Sep 17 00:00:00 2001 From: Dan Brown Date: Sun, 1 Feb 2026 16:27:52 +0000 Subject: [PATCH 6/8] Theme System: Split & organised tests, changed module version to string --- app/Theming/ThemeModule.php | 8 +- tests/TestCase.php | 18 ++ .../LogicalThemeEventsTest.php} | 273 ++---------------- tests/Theme/LogicalThemeTest.php | 105 +++++++ tests/Theme/VisualThemeTest.php | 132 +++++++++ 5 files changed, 278 insertions(+), 258 deletions(-) rename tests/{ThemeTest.php => Theme/LogicalThemeEventsTest.php} (50%) create mode 100644 tests/Theme/LogicalThemeTest.php create mode 100644 tests/Theme/VisualThemeTest.php diff --git a/app/Theming/ThemeModule.php b/app/Theming/ThemeModule.php index 9bbc0103ae5..f873ed247bd 100644 --- a/app/Theming/ThemeModule.php +++ b/app/Theming/ThemeModule.php @@ -9,7 +9,7 @@ class ThemeModule protected string $name; protected string $description; protected string $folderName; - protected int $version; + protected string $version; /** * Create a ThemeModule instance from JSON data. @@ -26,10 +26,14 @@ public static function fromJson(array $data, string $folderName): static throw new ThemeException("Module in folder \"{$folderName}\" is missing a valid 'description' property"); } - if (!isset($data['version']) || !is_int($data['version']) || $data['version'] < 1) { + if (!isset($data['version']) || !is_string($data['version'])) { throw new ThemeException("Module in folder \"{$folderName}\" is missing a valid 'version' property"); } + if (!preg_match('/^v?\d+\.\d+\.\d+(-.*)?$/', $data['version'])) { + throw new ThemeException("Module in folder \"{$folderName}\" has an invalid 'version' format. Expected semantic version format like '1.0.0' or 'v1.0.0'"); + } + $module = new static(); $module->name = $data['name']; $module->description = $data['description']; 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/ThemeTest.php b/tests/Theme/LogicalThemeEventsTest.php similarity index 50% rename from tests/ThemeTest.php rename to tests/Theme/LogicalThemeEventsTest.php index f640513cf1d..0a4afd2f4e3 100644 --- a/tests/ThemeTest.php +++ b/tests/Theme/LogicalThemeEventsTest.php @@ -1,6 +1,6 @@ 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() + public function test_commonmark_environment_configure() { $callbackCalled = false; $callback = function ($environment) use (&$callbackCalled) { @@ -83,7 +36,7 @@ public function test_event_commonmark_environment_configure() $this->assertTrue($callbackCalled); } - public function test_event_web_middleware_before() + public function test_web_middleware_before() { $callbackCalled = false; $requestParam = null; @@ -100,7 +53,7 @@ public function test_event_web_middleware_before() $this->assertEquals('cat', $requestParam->header('donkey')); } - public function test_event_web_middleware_before_return_val_used_as_response() + public function test_web_middleware_before_return_val_used_as_response() { $callback = function (Request $request) { return response('cat', 412); @@ -112,7 +65,7 @@ public function test_event_web_middleware_before_return_val_used_as_response() $resp->assertStatus(412); } - public function test_event_web_middleware_after() + public function test_web_middleware_after() { $callbackCalled = false; $requestParam = null; @@ -133,7 +86,7 @@ public function test_event_web_middleware_after() $resp->assertHeader('donkey', 'cat123'); } - public function test_event_web_middleware_after_return_val_used_as_response() + public function test_web_middleware_after_return_val_used_as_response() { $callback = function () { return response('cat456', 443); @@ -146,7 +99,7 @@ public function test_event_web_middleware_after_return_val_used_as_response() $resp->assertStatus(443); } - public function test_event_auth_login_standard() + public function test_auth_login_standard() { $args = []; $callback = function (...$eventArgs) use (&$args) { @@ -161,7 +114,7 @@ public function test_event_auth_login_standard() $this->assertInstanceOf(User::class, $args[1]); } - public function test_event_auth_register_standard() + public function test_auth_register_standard() { $args = []; $callback = function (...$eventArgs) use (&$args) { @@ -178,7 +131,7 @@ public function test_event_auth_register_standard() $this->assertInstanceOf(User::class, $args[1]); } - public function test_event_auth_pre_register() + public function test_auth_pre_register() { $args = []; $callback = function (...$eventArgs) use (&$args) { @@ -200,7 +153,7 @@ public function test_event_auth_pre_register() $this->assertDatabaseHas('users', ['email' => $user->email]); } - public function test_event_auth_pre_register_with_false_return_blocks_registration() + public function test_auth_pre_register_with_false_return_blocks_registration() { $callback = function () { return false; @@ -215,7 +168,7 @@ public function test_event_auth_pre_register_with_false_return_blocks_registrati $this->assertDatabaseMissing('users', ['email' => $user->email]); } - public function test_event_webhook_call_before() + public function test_webhook_call_before() { $args = []; $callback = function (...$eventArgs) use (&$args) { @@ -245,7 +198,7 @@ public function test_event_webhook_call_before() $this->assertEquals('hello!', $reqData['test']); } - public function test_event_activity_logged() + public function test_activity_logged() { $book = $this->entities->book(); $args = []; @@ -262,7 +215,7 @@ public function test_event_activity_logged() $this->assertEquals($book->id, $args[1]->id); } - public function test_event_page_include_parse() + public function test_page_include_parse() { /** @var Page $page */ /** @var Page $otherPage */ @@ -293,7 +246,7 @@ public function test_event_page_include_parse() $this->assertEquals($otherPage->id, $args[3]->id); } - public function test_event_routes_register_web_and_web_auth() + public function test_routes_register_web_and_web_auth() { $functionsContent = <<<'END' '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'); - }); - } - - public function test_theme_register_views_event_to_insert_views_before_and_after() + public function test_register_views_to_insert_views_before_and_after() { $this->usingThemeFolder(function (string $folder) { $before = 'this-is-my-before-header-string'; @@ -530,31 +318,4 @@ public function test_theme_register_views_event_to_insert_views_before_and_after $this->artisan('view:clear'); } - - 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!'); - } } 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/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'); + }); + } +} From 120ee38383c1a07f03405e88406a565dad1acc67 Mon Sep 17 00:00:00 2001 From: Dan Brown Date: Sun, 1 Feb 2026 17:31:21 +0000 Subject: [PATCH 7/8] Theme Modules: Added testing coverage --- app/Theming/ThemeModule.php | 26 ++-- tests/Theme/ThemeModuleTests.php | 223 +++++++++++++++++++++++++++++++ 2 files changed, 237 insertions(+), 12 deletions(-) create mode 100644 tests/Theme/ThemeModuleTests.php diff --git a/app/Theming/ThemeModule.php b/app/Theming/ThemeModule.php index f873ed247bd..594aa0701c7 100644 --- a/app/Theming/ThemeModule.php +++ b/app/Theming/ThemeModule.php @@ -6,17 +6,20 @@ class ThemeModule { - protected string $name; - protected string $description; - protected string $folderName; - protected string $version; + public function __construct( + public readonly string $name, + public readonly string $description, + public readonly string $folderName, + public readonly string $version, + ) { + } /** * Create a ThemeModule instance from JSON data. * * @throws ThemeException */ - public static function fromJson(array $data, string $folderName): static + public static function fromJson(array $data, string $folderName): self { if (empty($data['name']) || !is_string($data['name'])) { throw new ThemeException("Module in folder \"{$folderName}\" is missing a valid 'name' property"); @@ -34,13 +37,12 @@ public static function fromJson(array $data, string $folderName): static throw new ThemeException("Module in folder \"{$folderName}\" has an invalid 'version' format. Expected semantic version format like '1.0.0' or 'v1.0.0'"); } - $module = new static(); - $module->name = $data['name']; - $module->description = $data['description']; - $module->folderName = $folderName; - $module->version = $data['version']; - - return $module; + return new self( + name: $data['name'], + description: $data['description'], + folderName: $folderName, + version: $data['version'], + ); } /** 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); + }); + } +} From aa0a8dda114e0c0872ed11f8c69b6529aadab84f Mon Sep 17 00:00:00 2001 From: Dan Brown Date: Mon, 2 Feb 2026 18:29:35 +0000 Subject: [PATCH 8/8] Theme Modules: Added dev documentation --- app/Theming/ThemeModule.php | 10 +++--- dev/docs/logical-theme-system.md | 35 +++++++++++++++++++ dev/docs/theme-system-modules.md | 60 ++++++++++++++++++++++++++++++++ dev/docs/visual-theme-system.md | 5 ++- 4 files changed, 104 insertions(+), 6 deletions(-) create mode 100644 dev/docs/theme-system-modules.md diff --git a/app/Theming/ThemeModule.php b/app/Theming/ThemeModule.php index 594aa0701c7..12b1486beda 100644 --- a/app/Theming/ThemeModule.php +++ b/app/Theming/ThemeModule.php @@ -4,13 +4,13 @@ use BookStack\Exceptions\ThemeException; -class ThemeModule +readonly class ThemeModule { public function __construct( - public readonly string $name, - public readonly string $description, - public readonly string $folderName, - public readonly string $version, + public string $name, + public string $description, + public string $folderName, + public string $version, ) { } 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.