Writing a custom page error handler¶

The error handling configuration for sites allows implementing a custom error handler, if the existing options of rendering a Fluid template or page are not enough. An example would be an error page that uses the requested page or its parameters to search for relevant content on the website.

A custom error handler needs to have a constructor that takes exactly two arguments:

$statusCode: an integer holding the status code TYPO3 expects the handler to use
$configuration: an array holding the configuration of the handler

Furthermore it needs to implement the PageErrorHandlerInterface (EXT:core/Classes/Error/PageErrorHandler/PageErrorHandlerInterface.php). The interface specifies only one method: handlePageError(ServerRequestInterface $request, string $message, array $reasons = []): ResponseInterface

Let us take a closer look:

The method handlePageError() gets three parameters:

$request: the current HTTP request - for example, we can access query parameters and the request path via this object
$message: an error message string - for example, "Cannot connect to the configured database." or "Page not found"
$reasons: an arbitrary array of failure reasons - see, for example, \TYPO3\CMS\Frontend\Controller\TypoScriptFrontendController::getPageAccessFailureReasons

What you do with these variables is left to you, but you need to return a valid \Psr\Http\Message\ResponseInterface response - most usually an \TYPO3\CMS\Core\Http\HtmlResponse.

For an example implementation of the PageErrorHandlerInterface, take a look at EXT:core/Classes/Error/PageErrorHandler/PageContentErrorHandler.php or EXT:core/Classes/Error/PageErrorHandler/FluidPageErrorHandler.php.

Properties¶

The custom error handlers have the properties sitehandling-errorHandling_errorCode and sitehandling-errorHandling_errorHandler and the following:

errorPhpClassFQCN¶

Type: string
Example: MyVendor\MySitePackage\Error\MyErrorHandler

Fully-qualified class name of a custom error handler implementing PageErrorHandlerInterface.

Example for a simple 404 error handler¶

The configuration:

config/sites/<some_site>/config.yaml | typo3conf/sites/<some_site>/config.yaml¶

errorHandling:
  - errorCode: '404'
    errorHandler: PHP
    errorPhpClassFQCN: MyVendor\MySitePackage\Error\MyErrorHandler

The error handler class:

EXT:my_sitepackage/Classes/Error/MyErrorHandler.php¶

<?php

declare(strict_types=1);

namespace MyVendor\MySitePackage\Error;

use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use TYPO3\CMS\Core\Error\PageErrorHandler\PageErrorHandlerInterface;
use TYPO3\CMS\Core\Http\HtmlResponse;

final class ErrorHandler implements PageErrorHandlerInterface
{
    private int $statusCode;
    private array $errorHandlerConfiguration;

    public function __construct(int $statusCode, array $configuration)
    {
        $this->statusCode = $statusCode;
        // This contains the configuration of the error handler which is
        // set in site configuration - this example does not use it.
        $this->errorHandlerConfiguration = $configuration;
    }

    public function handlePageError(
        ServerRequestInterface $request,
        string $message,
        array $reasons = []
    ): ResponseInterface {
        return new HtmlResponse('<h1>Not found, sorry</h1>', $this->statusCode);
    }
}