BookStack Code Mirror - bookstack/blob - app/Theming/ThemeEvents.php

   1 <?php
   2
   3 namespace BookStack\Theming;
   4
   5 use BookStack\Entities\Models\Page;
   6
   7 /**
   8  * The ThemeEvents used within BookStack.
   9  *
  10  * This file details the events that BookStack may fire via the custom
  11  * theme system, including event names, parameters and expected return types.
  12  *
  13  * This system is regarded as semi-stable.
  14  * We'll look to fix issues with it or migrate old event types but
  15  * events and their signatures may change in new versions of BookStack.
  16  * We'd advise testing any usage of these events upon upgrade.
  17  */
  18 class ThemeEvents
  19 {
  20     /**
  21      * Activity logged event.
  22      * Runs right after an activity is logged by bookstack.
  23      * These are the activities that can be seen in the audit log area of BookStack.
  24      * Activity types can be seen listed in the \BookStack\Actions\ActivityType class.
  25      * The provided $detail can be a string or a loggable type of model. You should check
  26      * the type before making use of this parameter.
  27      *
  28      * @param string                                $type
  29      * @param string|\BookStack\Activity\Models\Loggable $detail
  30      */
  31     const ACTIVITY_LOGGED = 'activity_logged';
  32
  33     /**
  34      * Application boot-up.
  35      * After main services are registered.
  36      *
  37      * @param \BookStack\App\Application $app
  38      */
  39     const APP_BOOT = 'app_boot';
  40
  41     /**
  42      * Auth login event.
  43      * Runs right after a user is logged-in to the application by any authentication
  44      * system as a standard app user. This includes a user becoming logged in
  45      * after registration. This is not emitted upon API usage.
  46      *
  47      * @param string               $authSystem
  48      * @param \BookStack\Users\Models\User $user
  49      */
  50     const AUTH_LOGIN = 'auth_login';
  51
  52     /**
  53      * Auth register event.
  54      * Runs right after a user is newly registered to the application by any authentication
  55      * system as a standard app user. This includes auto-registration systems used
  56      * by LDAP, SAML and social systems. It only includes self-registrations.
  57      *
  58      * @param string               $authSystem
  59      * @param \BookStack\Users\Models\User $user
  60      */
  61     const AUTH_REGISTER = 'auth_register';
  62
  63     /**
  64      * Commonmark environment configure.
  65      * Provides the commonmark library environment for customization before it's used to render markdown content.
  66      * If the listener returns a non-null value, that will be used as an environment instead.
  67      *
  68      * @param \League\CommonMark\Environment\Environment $environment
  69      * @returns \League\CommonMark\Environment\Environment|null
  70      */
  71     const COMMONMARK_ENVIRONMENT_CONFIGURE = 'commonmark_environment_configure';
  72
  73     /**
  74      * OIDC ID token pre-validate event.
  75      * Runs just before BookStack validates the user ID token data upon login.
  76      * Provides the existing found set of claims for the user as a key-value array,
  77      * along with an array of the proceeding access token data provided by the identity platform.
  78      * If the listener returns a non-null value, that will replace the existing ID token claim data.
  79      *
  80      * @param array $idTokenData
  81      * @param array $accessTokenData
  82      * @returns array|null
  83      */
  84     const OIDC_ID_TOKEN_PRE_VALIDATE = 'oidc_id_token_pre_validate';
  85
  86     /**
  87      * Page include parse event.
  88      * Runs when a page include tag is being parsed, typically when page content is being processed for viewing.
  89      * Provides the "include tag" reference string, the default BookStack replacement content for the tag,
  90      * the current page being processed, and the page that's being referenced by the include tag.
  91      * The referenced page may be null where the page does not exist or where permissions prevent visibility.
  92      * If the listener returns a non-null value, that will be used as the replacement HTML content instead.
  93      *
  94      * @param string $tagReference
  95      * @param string $replacementHTML
  96      * @param Page   $currentPage
  97      * @param ?Page  $referencedPage
  98      */
  99     const PAGE_INCLUDE_PARSE = 'page_include_parse';
 100
 101     /**
 102      * Routes register web event.
 103      * Called when standard web (browser/non-api) app routes are registered.
 104      * Provides an app router, so you can register your own web routes.
 105      *
 106      * @param \Illuminate\Routing\Router
 107      */
 108     const ROUTES_REGISTER_WEB = 'routes_register_web';
 109
 110     /**
 111      * Routes register web auth event.
 112      * Called when auth-required web (browser/non-api) app routes can be registered.
 113      * These are routes that typically require login to access (unless the instance is made public).
 114      * Provides an app router, so you can register your own web routes.
 115      *
 116      * @param \Illuminate\Routing\Router
 117      */
 118     const ROUTES_REGISTER_WEB_AUTH = 'routes_register_web_auth';
 119
 120     /**
 121      * Web before middleware action.
 122      * Runs before the request is handled but after all other middleware apart from those
 123      * that depend on the current session user (Localization for example).
 124      * Provides the original request to use.
 125      * Return values, if provided, will be used as a new response to use.
 126      *
 127      * @param \Illuminate\Http\Request $request
 128      * @returns \Illuminate\Http\Response|null
 129      */
 130     const WEB_MIDDLEWARE_BEFORE = 'web_middleware_before';
 131
 132     /**
 133      * Web after middleware action.
 134      * Runs after the request is handled but before the response is sent.
 135      * Provides both the original request and the currently resolved response.
 136      * Return values, if provided, will be used as a new response to use.
 137      *
 138      * @param \Illuminate\Http\Request                                                       $request
 139      * @param \Illuminate\Http\Response|\Symfony\Component\HttpFoundation\BinaryFileResponse $response
 140      * @returns \Illuminate\Http\Response|null
 141      */
 142     const WEB_MIDDLEWARE_AFTER = 'web_middleware_after';
 143
 144     /**
 145      * Webhook call before event.
 146      * Runs before a webhook endpoint is called. Allows for customization
 147      * of the data format & content within the webhook POST request.
 148      * Provides the original event name as a string (see \BookStack\Actions\ActivityType)
 149      * along with the webhook instance along with the event detail which may be a
 150      * "Loggable" model type or a string.
 151      * If the listener returns a non-null value, that will be used as the POST data instead
 152      * of the system default.
 153      *
 154      * @param string                                     $event
 155      * @param \BookStack\Activity\Models\Webhook         $webhook
 156      * @param string|\BookStack\Activity\Models\Loggable $detail
 157      * @param \BookStack\Users\Models\User               $initiator
 158      * @param int                                        $initiatedTime
 159      * @returns array|null
 160      */
 161     const WEBHOOK_CALL_BEFORE = 'webhook_call_before';
 162 }