.. ================================================== .. FOR YOUR INFORMATION .. -------------------------------------------------- .. -*- coding: utf-8 -*- with BOM. .. include:: ../Includes.txt .. _admin-manual: Administrator Manual ==================== Installation ------------ Install the extension with the extension manager. Extension configuration ----------------------- The following settings are available in the Extension manager of the TYPO3 backend. +--------------------------------+--------------------------------------------------------------------------+ | Property | Description | +================================+==========================================================================+ | :code:`404.enable` | Registers :code:`$TYPO3_CONF_VARS['FE']['pageNotFound_handling']` | +--------------------------------+--------------------------------------------------------------------------+ | :code:`503.enable` | Registers :code:`$TYPO3_CONF_VARS['FE']['pageUnavailable_handling']` | +--------------------------------+--------------------------------------------------------------------------+ | :code:`exception.enable` | Registers :code:`$TYPO3_CONF_VARS['SYS']['productionExceptionHandler']` | +--------------------------------+--------------------------------------------------------------------------+ | :code:`compression.enable` | Enable compression of statically cached files | +--------------------------------+--------------------------------------------------------------------------+ | :code:`page.type` | Page property "Error type" (single or multi select) | +--------------------------------+--------------------------------------------------------------------------+ | :code:`page.level` | Page property "Target pages" (disabled, single or multi select) | +--------------------------------+--------------------------------------------------------------------------+ Error groups ------------ There are four preconfigured error groups. They can be overwritten or modified in :code:`typo3conf/AdditionalLocalConfiguration.php` or :code:`ext_localconf.php` of other extensions. .. code-block:: php $TYPO3_CONF_VARS['EXTCONF']['form4_errordocs']['errorGroups'] = [ '404' => [ 'label' => 'Page not found', 'pageNotFoundHandling' => true, 'statusExceptions' => [404], ], '403' => [ 'label' => 'Permission denied', 'statusExceptions' => [403], ], '4xx' => [ 'label' => 'Client errors', 'statusExceptions' => ['/4\d{2}/'], ], '5xx' => [ 'label' => 'Server errors', 'pageUnavailableHandling' => true, 'exceptions' => true, ], ]; Explanation by example ++++++++++++++++++++++ - The keys (:code:`404`, :code:`403`, :code:`4xx`, ...) are used to generate the file names of the statically cached error documents. - The :code:`label` is displayed in the error type selector in the page settings. - When setting :code:`pageNotFoundHandling` to :code:`true` this error group is used by :code:`$TYPO3_CONF_VARS['FE']['pageNotFound_handling']`. - When setting :code:`pageUnavailableHandling` to :code:`true` this error group is used by :code:`$TYPO3_CONF_VARS['FE']['pageUnavailable_handling']`. - When setting :code:`exceptions` to :code:`true` this error group is used as the default behaviour for :code:`$TYPO3_CONF_VARS['SYS']['productionExceptionHandler']`. - :code:`statusExceptions` must be an array of integers or strings containing a regular expression. When an exception contains the method :code:`getStatusHeaders()` the exception handler loops through the headers and tries to find a suitable error group by matching the header against the elements of :code:`statusExceptions`. E.g.: an exception with header :code:`HTTP/1.1 403 Forbidden` would match error group :code:`403` and header :code:`HTTP/1.1 405 Method Not Allowed` would match error group :code:`4xx`. There should be only one error group at a time using :code:`pageNotFoundHandling`, :code:`pageUnavailableHandling` and :code:`exceptions`. Otherwise the first defined one is used. The same goes for patterns listed in :code:`statusExceptions`. Handle specific exceptions ++++++++++++++++++++++++++ Furthermore error groups can be configured to handle specific exceptions. Besides being :code:`true` the setting :code:`exceptions` can be a string or an array. If it's a string, it must be the name of a class or an interface. If it's an array it must contain class and/or interface names. If a catched exception extends/implements more than one of the configured classes/interfaces the highest one in its inheritance hierarchy matches. If an exception doesn't match any error group, the error group with :code:`'exceptions' => true` is used. .. code-block:: php $TYPO3_CONF_VARS['EXTCONF']['form4_errordocs']['errorGroups'] = [ '404' => [ 'label' => 'Page not found', 'pageNotFoundHandling' => true, 'statusExceptions' => [404], 'exceptions' => [ \Vendor\Project\Exceptions\BlogPostNotFoundException::class, \Vendor\Project\Exceptions\UserNotFoundException::class, ], ], ... ]; Static cache ------------ When an error page is updated, it gets statically cached in :code:`uploads/tx_form4errordocs/{scheme}/{hostName}[/{pagePath}]/{errorGroup}.html[.gz]`. This way the webserver can use these files as error documents. The directory path can be overwritten in :code:`typo3conf/AdditionalLocalConfiguration.php` or :code:`ext_localconf.php` of other extensions. The path can be either absolute or relative to the TYPO3 installation. .. code-block:: php $GLOBALS['TYPO3_CONF_VARS']['SYS']['caching']['cacheConfigurations']['form4_errordocs']['options']['cacheDirectory'] = 'uploads/tx_form4errordocs/' Default language ---------------- Per default this feature is deactivated. It can be overwritten with a SysLanguageUid in :code:`typo3conf/AdditionalLocalConfiguration.php` or :code:`ext_localconf.php` of other extensions. .. code-block:: php $TYPO3_CONF_VARS['EXTCONF']['form4_errordocs']['defaultLanguage'] = 0; For websites that always use URLs with a language prefix (e.g. *http://example.org/en/...*) this setting determines which translation of a root error page is stored without an URL path (:code:`uploads/tx_form4errordocs/{scheme}/{hostName}/{errorGroup}.html[.gz]`). If it is :code:`null` or :code:`false` this feature is deactivated. Explanation by example ++++++++++++++++++++++ A website has the language prefixes */en/* and */de/* - */en/* for SysLanguageUid :code:`0` and */de/* for SysLanguageUid :code:`1`. Because the path generation of error pages relies on realurl (or similar extensions) there wouldn't be error pages for paths like */invalid/url/*. By configuring :code:`...['defaultLanguage'] = 1` the extension uses the error pages from */de/* as error pages for URLs that don't match one of the language prefixes. Apache web server ----------------- The following configuration can be added to a :code:`.htacces` file right below :code:`RewriteEngine On`. It fits the preconfigured :code:`TYPO3_CONF_VARS['EXTCONF']['form4_errordocs']['errorGroups']` and should be adapted when another error group configuration is used. :: RewriteCond %{HTTPS} off RewriteRule .* - [E=REQUEST_SCHEME:http] RewriteCond %{HTTPS} on RewriteRule .* - [E=REQUEST_SCHEME:https] ErrorDocument 400 / ErrorDocument 401 / ErrorDocument 402 / ErrorDocument 403 / ErrorDocument 404 / ErrorDocument 405 / ErrorDocument 406 / ErrorDocument 407 / ErrorDocument 408 / ErrorDocument 409 / ErrorDocument 410 / ErrorDocument 411 / ErrorDocument 412 / ErrorDocument 413 / ErrorDocument 414 / ErrorDocument 415 / ErrorDocument 416 / ErrorDocument 417 / ErrorDocument 500 / ErrorDocument 501 / ErrorDocument 502 / ErrorDocument 503 / ErrorDocument 504 / ErrorDocument 505 / RewriteCond %{ENV:REDIRECT_STATUS} "=404" RewriteRule (.*) %{CONTEXT_DOCUMENT_ROOT}/uploads/tx_form4errordocs/%{ENV:REQUEST_SCHEME}/%{HTTP_HOST}/404.html [L] RewriteCond %{ENV:REDIRECT_STATUS} "=403" RewriteRule (.*) %{CONTEXT_DOCUMENT_ROOT}/uploads/tx_form4errordocs/%{ENV:REQUEST_SCHEME}/%{HTTP_HOST}/403.html [L] RewriteCond %{ENV:REDIRECT_STATUS} 4[0-9]{2} RewriteRule (.*) %{CONTEXT_DOCUMENT_ROOT}/uploads/tx_form4errordocs/%{ENV:REQUEST_SCHEME}/%{HTTP_HOST}/4xx.html [L] RewriteCond %{ENV:REDIRECT_STATUS} 5[0-9]{2} RewriteRule (.*) %{CONTEXT_DOCUMENT_ROOT}/uploads/tx_form4errordocs/%{ENV:REQUEST_SCHEME}/%{HTTP_HOST}/5xx.html [L] Status Reports -------------- The extension contains four status providers, that check for common configuration errors. - Conflicting error group configurations - One for :code:`pageNotFoundHandling`, :code:`pageUnavailableHandling` and :code:`exceptions` - Another one for :code:`statusExceptions` - Root sites with unhandled error groups - Conflicting error pages, i.e. multiple error pages for the same error group on the same parent page .. figure:: ../Images/StatusReports.png :width: 800px :alt: Status Reports .. figure:: ../Images/StatusReports2.png :width: 800px :alt: Status Reports Scheduler Task -------------- The extension comes with a scheduler task that flushes and rebuilds the static file cache. Test plugin ----------- The extension contains a simple plugin for testing the TYPO3 error handling. It can call/throw - :code:`$TSFE->pageNotFoundAndExit()` - :code:`$TSFE->pageUnavailableAndExit()` - :code:`\Exception` - :code:`\TYPO3\CMS\Core\Error\Http\StatusException` Because by default an exception in a plugin does not cause an error page to be displayed, there's a TypoScript template that changes this behaviour (:code:`config.contentObjectExceptionHandler = 0`). For this reason the template should only be included in a TypoScript template record of the page with this plugin.