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
totrue
this error group is used by$TYPO3_CONF_VARS['FE']['pageNotFound_handling']
. - When setting
pageUnavailableHandling
totrue
this error group is used by$TYPO3_CONF_VARS['FE']['pageUnavailable_handling']
. - When setting
exceptions
totrue
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 methodgetStatusHeaders()
the exception handler loops through the headers and tries to find a suitable error group by matching the header against the elements ofstatusExceptions
. E.g.: an exception with headerHTTP/1.1 403 Forbidden
would match error group403
and headerHTTP/1.1 405 Method Not Allowed
would match error group4xx
.
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
andexceptions
- Another one forstatusExceptions
- Root sites with unhandled error groups
- Conflicting error pages, i.e. multiple error pages for the same error group on the same parent page
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.