[PR #2639] [MERGED] WIP: Backend theme system #6041

New Issue

OVERLORD · 2026-02-05T10:23:14+03:00

OVERLORD commented

2026-02-05 10:23:14 +03:00

📋 Pull Request Information

Original PR: https://github.com/BookStackApp/BookStack/pull/2639
Author: @ssddanbrown
Created: 3/16/2021
Status: ✅ Merged
Merged: 3/20/2021
Merged by: @ssddanbrown

Base: master ← Head: backend_theme_system

📝 Commits (7)

c61c3bc Started backend theme system
a5d2a26 Added testing for the back-end theme system done so far
9d37af9 Added web-middleware based theme events
2ae89f2 Added the possibility of social provider extension via theme
691db40 Added login/register theme events
a92c35a Worked on theme system documentation
44a293f Fleshed out and checked over theme system docs

📊 Changes

23 files changed (+606 additions, -53 deletions)

View changed files

📝 app/Auth/Access/Guards/LdapSessionGuard.php (+0 -2)
📝 app/Auth/Access/RegistrationService.php (+3 -0)
📝 app/Auth/Access/Saml2Service.php (+3 -0)
📝 app/Auth/Access/SocialAuthService.php (+34 -20)
📝 app/Config/app.php (+2 -0)
📝 app/Entities/Tools/PageContent.php (+3 -0)
➕ app/Facades/Theme.php (+16 -0)
📝 app/Http/Controllers/Auth/ConfirmEmailController.php (+5 -0)
📝 app/Http/Controllers/Auth/LoginController.php (+3 -0)
📝 app/Http/Controllers/Auth/RegisterController.php (+5 -0)
📝 app/Http/Controllers/Auth/SocialController.php (+6 -1)
📝 app/Http/Controllers/Auth/UserInviteController.php (+5 -0)
📝 app/Http/Kernel.php (+1 -0)
➕ app/Http/Middleware/RunThemeActions.php (+29 -0)
📝 app/Providers/AppServiceProvider.php (+6 -0)
📝 app/Providers/CustomFacadeProvider.php (+5 -0)
➕ app/Providers/ThemeServiceProvider.php (+34 -0)
➕ app/Theming/ThemeEvents.php (+73 -0)
➕ app/Theming/ThemeService.php (+61 -0)
➕ dev/docs/logical-theme-system.md (+98 -0)

...and 3 more files

📄 Description

Overview

This essentially allows customization of back-end components using the theme folder that we already have for views/translations/icons. Using this you'll be able to hook into specific back-end events to add & modify functionality for your own use-case.

This system will look for a functions.php file within your configure theme, and run that during application boot. Within this file you could register event handlers.

The events available, and their parameters and return options, will be documented within the codebase within a class that holds static references for the event names. This can be previewed here: https://github.com/BookStackApp/BookStack/blob/backend_theme_system/app/Theming/ThemeEvents.php

Multiple event handlers could be added per event, but if a handler returns a non-null value then no further handlers will be called during that event emission. This allows return values of handlers to be used where required with relative ease.

The initial implementation will be considered unstable with the intention of being open to feedback, then in the future we'll deem this semi-stable, with the core event system being maintained but the event details being subject to change over BookStack releases as to limit core project maintenance and development burden.

Usage Examples

Customization of the markdown renderer.
Custom logic implementation on boot.
Custom events on user login/register.
Custom middleware-style logic with ease.
Custom socialite provider additions.

Todo

Add and test events to match the above examples for an initial implementation.
Add some documentation for this system with a md file within the project devdocs folder.

Example theme `functions.php` file

<?php

use BookStack\Facades\Theme;
use BookStack\Theming\ThemeEvents;
use League\CommonMark\ConfigurableEnvironmentInterface;
use League\CommonMark\Extension\Footnote\FootnoteExtension;

Theme::listen(ThemeEvents::APP_BOOT, function($app) {
    \Log::info('app-boot');
});

Theme::listen(ThemeEvents::COMMONMARK_ENVIRONMENT_CONFIGURE, function(ConfigurableEnvironmentInterface $environment) {
    $environment->addExtension(new FootnoteExtension());
});

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/BookStackApp/BookStack/pull/2639 **Author:** [@ssddanbrown](https://github.com/ssddanbrown) **Created:** 3/16/2021 **Status:** ✅ Merged **Merged:** 3/20/2021 **Merged by:** [@ssddanbrown](https://github.com/ssddanbrown) **Base:** `master` ← **Head:** `backend_theme_system` --- ### 📝 Commits (7) - [`c61c3bc`](https://github.com/BookStackApp/BookStack/commit/c61c3bc60890f171589f3fcdccbe217c900af1c1) Started backend theme system - [`a5d2a26`](https://github.com/BookStackApp/BookStack/commit/a5d2a26fccbc1ffd2f41707954047f13cc12fa57) Added testing for the back-end theme system done so far - [`9d37af9`](https://github.com/BookStackApp/BookStack/commit/9d37af94537d40b32d9d7416d54fa8fc0e0169e9) Added web-middleware based theme events - [`2ae89f2`](https://github.com/BookStackApp/BookStack/commit/2ae89f2c321b5974ed3733ae40f5e5496b21f9f4) Added the possibility of social provider extension via theme - [`691db40`](https://github.com/BookStackApp/BookStack/commit/691db40a3330cb7518a0d06eadc62ec03415067d) Added login/register theme events - [`a92c35a`](https://github.com/BookStackApp/BookStack/commit/a92c35a7acd712c5c9e55be502e964b0aa17bcd2) Worked on theme system documentation - [`44a293f`](https://github.com/BookStackApp/BookStack/commit/44a293f05190f1e78a7c51d7357e752283f7bd29) Fleshed out and checked over theme system docs ### 📊 Changes **23 files changed** (+606 additions, -53 deletions) <details> <summary>View changed files</summary> 📝 `app/Auth/Access/Guards/LdapSessionGuard.php` (+0 -2) 📝 `app/Auth/Access/RegistrationService.php` (+3 -0) 📝 `app/Auth/Access/Saml2Service.php` (+3 -0) 📝 `app/Auth/Access/SocialAuthService.php` (+34 -20) 📝 `app/Config/app.php` (+2 -0) 📝 `app/Entities/Tools/PageContent.php` (+3 -0) ➕ `app/Facades/Theme.php` (+16 -0) 📝 `app/Http/Controllers/Auth/ConfirmEmailController.php` (+5 -0) 📝 `app/Http/Controllers/Auth/LoginController.php` (+3 -0) 📝 `app/Http/Controllers/Auth/RegisterController.php` (+5 -0) 📝 `app/Http/Controllers/Auth/SocialController.php` (+6 -1) 📝 `app/Http/Controllers/Auth/UserInviteController.php` (+5 -0) 📝 `app/Http/Kernel.php` (+1 -0) ➕ `app/Http/Middleware/RunThemeActions.php` (+29 -0) 📝 `app/Providers/AppServiceProvider.php` (+6 -0) 📝 `app/Providers/CustomFacadeProvider.php` (+5 -0) ➕ `app/Providers/ThemeServiceProvider.php` (+34 -0) ➕ `app/Theming/ThemeEvents.php` (+73 -0) ➕ `app/Theming/ThemeService.php` (+61 -0) ➕ `dev/docs/logical-theme-system.md` (+98 -0) _...and 3 more files_ </details> ### 📄 Description ### Overview This essentially allows customization of back-end components using the theme folder that we already have for views/translations/icons. Using this you'll be able to hook into specific back-end events to add & modify functionality for your own use-case. This system will look for a `functions.php` file within your configure theme, and run that during application boot. Within this file you could register event handlers. The events available, and their parameters and return options, will be documented within the codebase within a class that holds static references for the event names. This can be previewed here: https://github.com/BookStackApp/BookStack/blob/backend_theme_system/app/Theming/ThemeEvents.php Multiple event handlers could be added per event, but if a handler returns a non-null value then no further handlers will be called during that event emission. This allows return values of handlers to be used where required with relative ease. The initial implementation will be considered unstable with the intention of being open to feedback, then in the future we'll deem this semi-stable, with the core event system being maintained but the event details being subject to change over BookStack releases as to limit core project maintenance and development burden. ### Usage Examples - [x] Customization of the markdown renderer. - [x] Custom logic implementation on boot. - [x] Custom events on user login/register. - [x] Custom middleware-style logic with ease. - [x] Custom socialite provider additions. ### Todo - [x] Add and test events to match the above examples for an initial implementation. - [x] Add some documentation for this system with a md file within the project devdocs folder. ### Example theme `functions.php` file ```php <?php use BookStack\Facades\Theme; use BookStack\Theming\ThemeEvents; use League\CommonMark\ConfigurableEnvironmentInterface; use League\CommonMark\Extension\Footnote\FootnoteExtension; Theme::listen(ThemeEvents::APP_BOOT, function($app) { \Log::info('app-boot'); }); Theme::listen(ThemeEvents::COMMONMARK_ENVIRONMENT_CONFIGURE, function(ConfigurableEnvironmentInterface $environment) { $environment->addExtension(new FootnoteExtension()); }); ``` --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

OVERLORD added the pull-request label 2026-02-05 10:23:14 +03:00

OVERLORD closed this issue

2026-02-05 10:23:15 +03:00

Sign in to join this conversation.

Branches Tags

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: starred/BookStack#6041

[PR #2639] [MERGED] WIP: Backend theme system #6041