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

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