WIP: Backend theme system

[ssddanbrown]

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());
});