DEPRECATION WARNING

This documentation is not using the current rendering mechanism and is probably outdated. The extension maintainer should switch to the new system. Details on how to use the rendering mechanism can be found here.

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
404.enable Registers $TYPO3_CONF_VARS['FE']['pageNotFound_handling']
503.enable Registers $TYPO3_CONF_VARS['FE']['pageUnavailable_handling']
exception.enable Registers $TYPO3_CONF_VARS['SYS']['productionExceptionHandler']
compression.enable Enable compression of statically cached files
page.type Page property “Error type” (single or multi select)
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 typo3conf/AdditionalLocalConfiguration.php or ext_localconf.php of other extensions.

$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 (404, 403, 4xx, …) are used to generate the file names of the statically cached error documents.
  • The label is displayed in the error type selector in the page settings.
  • When setting pageNotFoundHandling to true this error group is used by $TYPO3_CONF_VARS['FE']['pageNotFound_handling'].
  • When setting pageUnavailableHandling to true this error group is used by $TYPO3_CONF_VARS['FE']['pageUnavailable_handling'].
  • When setting exceptions to true this error group is used as the default behaviour for $TYPO3_CONF_VARS['SYS']['productionExceptionHandler'].
  • statusExceptions must be an array of integers or strings containing a regular expression. When an exception contains the method getStatusHeaders() the exception handler loops through the headers and tries to find a suitable error group by matching the header against the elements of statusExceptions. E.g.: an exception with header HTTP/1.1 403 Forbidden would match error group 403 and header HTTP/1.1 405 Method Not Allowed would match error group 4xx.

There should be only one error group at a time using pageNotFoundHandling, pageUnavailableHandling and exceptions. Otherwise the first defined one is used. The same goes for patterns listed in statusExceptions.

Handle specific exceptions

Furthermore error groups can be configured to handle specific exceptions.

Besides being true the setting 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 'exceptions' => true is used.

$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 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 typo3conf/AdditionalLocalConfiguration.php or ext_localconf.php of other extensions.

The path can be either absolute or relative to the TYPO3 installation.

$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 typo3conf/AdditionalLocalConfiguration.php or ext_localconf.php of other extensions.

$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 (uploads/tx_form4errordocs/{scheme}/{hostName}/{errorGroup}.html[.gz]).

If it is null or false this feature is deactivated.

Explanation by example

A website has the language prefixes /en/ and /de/ - /en/ for SysLanguageUid 0 and /de/ for SysLanguageUid 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 ...['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 .htacces file right below RewriteEngine On.

It fits the preconfigured 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 pageNotFoundHandling, pageUnavailableHandling and exceptions - Another one for 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
Status Reports
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

  • $TSFE->pageNotFoundAndExit()
  • $TSFE->pageUnavailableAndExit()
  • \Exception
  • \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 (config.contentObjectExceptionHandler = 0). For this reason the template should only be included in a TypoScript template record of the page with this plugin.