Middlewares (Request handling)

Basic concept

The most important information is available at https://www.php-fig.org/psr/psr-15/ and https://www.php-fig.org/psr/psr-15/meta/ where the standard itself is explained.

The idea is to use PSR-7 Request and Response as a base, and wrap the execution with middlewares which implement PSR-15. PSR-15 will receive the incoming request and return the created response. Within PSR-15 multiple request handlers and middlewares can be executed. Each of them can adjust the request and response.

TYPO3 implementation

TYPO3 has implemented the PSR-15 approach in the following way:

1. TYPO3 will create a TYPO3 request object.
2. TYPO3 will collect and sort all configured PSR-15 middlewares.
3. TYPO3 will convert all middlewares to PSR-15 request handlers.
4. TYPO3 will call the first middleware with request and the next middleware.
5. Each middleware can modify the request if needed, see Middlewares.
6. Final Request is passed to the last RequestHandler (\TYPO3\CMS\Frontend\Http\RequestHandler or \TYPO3\CMS\Backend\Http\RequestHandler) which generates PSR-7 response and passes it back to the last middleware.
7. Each middleware gets back a PSR-7 response from middleware later in the stack and passes it up the stack to the previous middleware. Each middleware can modify the response before passing it back.
8. This response is passed back to the execution flow.

Middlewares

Each middleware has to implement the PSR-15 \Psr\Http\Server\MiddlewareInterface :

interface MiddlewareInterface

Fully qualified name

\Psr\Http\Server\MiddlewareInterface

Participant in processing a server request and response.

An HTTP middleware component participates in processing an HTTP message: by acting on the request, generating the response, or forwarding the request to a subsequent middleware and possibly acting on its response.

process ( \Psr\Http\Message\ServerRequestInterface $request, \Psr\Http\Server\RequestHandlerInterface $handler)

Process an incoming server request.

Processes an incoming server request in order to produce a response. If unable to produce the response itself, it may delegate to the provided request handler to do so.

param $request

the request

param $handler

the handler

Returns

\Psr\Http\Message\ResponseInterface

By doing so, the middleware can do one or multiple of the following:

• Adjust the incoming request, e.g. add further information.
• Create and return a PSR-7 response.
• Call next request handler (which again can be a middleware).
• Adjust response received from the next request handler.

Middleware examples

The following list shows typical use cases for middlewares.

• A middleware to return a JSON response with localized strings.

<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Middleware;

use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\MiddlewareInterface;
use Psr\Http\Server\RequestHandlerInterface;
use TYPO3\CMS\Core\Utility\GeneralUtility;
use TYPO3\CMS\Frontend\Controller\ErrorController;

class NotAvailableMiddleware implements MiddlewareInterface
{
    public function process(
        ServerRequestInterface $request,
        RequestHandlerInterface $handler,
    ): ResponseInterface {
        if ($request->getRequestTarget() === 'foo/bar') {
            return GeneralUtility::makeInstance(ErrorController::class)
                ->unavailableAction(
                    $request,
                    'This page is temporarily unavailable.',
                );
        }

        return $handler->handle($request);
    }
}

<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Middleware;

use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\MiddlewareInterface;
use Psr\Http\Server\RequestHandlerInterface;
use TYPO3\CMS\Core\Routing\RouterInterface;

class RequestEnrichingMiddleware implements MiddlewareInterface
{
    public function __construct(
        private readonly RouterInterface $matcher,
    ) {}

    public function process(
        ServerRequestInterface $request,
        RequestHandlerInterface $handler,
    ): ResponseInterface {
        $routeResult = $this->matcher->matchRequest($request);

        $request = $request->withAttribute('site', $routeResult->getSite());
        $request = $request->withAttribute('language', $routeResult->getLanguage());

        return $handler->handle($request);
    }
}

<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Middleware;

use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\MiddlewareInterface;
use Psr\Http\Server\RequestHandlerInterface;

class RequestEnrichingMiddleware implements MiddlewareInterface
{
    public function process(
        ServerRequestInterface $request,
        RequestHandlerInterface $handler,
    ): ResponseInterface {
        $response = $handler->handle($request);

        if ($request->getRequestTarget() === 'foo/bar') {
            $response = $response->withHeader(
                'Content-Length',
                (string)$response->getBody()->getSize(),
            );
        }

        return $response;
    }
}

Configuring middlewares

In order to implement a custom middleware, this middleware has to be configured. TYPO3 already provides some middlewares out of the box. Beside adding your own middlewares, it's also possible to remove existing middlewares from the configuration.

The configuration is provided within Configuration/RequestMiddlewares.php of an extension:

return [
    'frontend' => [
        'middleware-identifier' => [
            'target' => \Vendor\SomeExtension\Middleware\ConcreteClass::class,
            'before' => [
                'another-middleware-identifier',
            ],
            'after' => [
                'yet-another-middleware-identifier',
            ],
        ],
    ],
    'backend' => [
        'middleware-identifier' => [
            'target' => \Vendor\SomeExtension\Middleware\AnotherConcreteClass::class,
            'before' => [
                'another-middleware-identifier',
            ],
            'after' => [
                'yet-another-middleware-identifier',
            ],
        ],
    ],
];

TYPO3 has multiple stacks where one middleware might only be necessary in one of them. Therefore the configuration defines the context on its first level to define the context. Within each context the middleware is registered as new subsection with an unique identifier as key.

The default stacks are: frontend and backend.

Each middleware consists of the following options:

target

PHP string

FQCN (=Fully Qualified Class Name) to use as middleware.

before

PHP Array

List of middleware identifiers. The middleware itself is executed before any other middleware within this array.

after

PHP Array

List of middleware identifiers. The middleware itself is executed after any other middleware within this array.

disabled

PHP boolean

Allows to disable specific middlewares.

The before and after configuration is used to sort middlewares in form of a stack. You can check the calculated order in the configuration module in TYPO3 Backend.

Middleware which is configured before another middleware (higher in the stack) wraps execution of following middlewares. Code written before $handler->handle($request); in the process method can modify the request before it's passed to the next middlewares. Code written after $handler->handle($request); can modify the response provided by next middlewares.

Middleware which is configured after another (e.g. MiddlewareB from the diagram above), will see changes to the request made by previous middleware (MiddlewareA), but will not see changes made to the response from MiddlewareA.

Override ordering of middlewares

To change the ordering of middlewares shipped by the Core an extension can override the registration in Configuration/RequestMiddlewares.php:

<?php

return [
    'frontend' => [
        'middleware-identifier' => [
            'after' => [
                'another-middleware-identifier',
            ],
            'before' => [
                '3rd-middleware-identifier',
            ],
        ],
    ],
];

However, this could lead to circular ordering depending on the ordering constraints of other middlewares. Alternatively an existing middleware can be disabled and reregistered again with a new identifier. This will circumvent the risk of circularity:

<?php

return [
    'frontend' => [
        'middleware-identifier' => [
            'disabled' => true,
        ],
        'overwrite-middleware-identifier' => [
            'target' => \MyVendor\SomeExtension\Middleware\MyMiddleware::class,
            'after' => [
                'another-middleware-identifier',
            ],
            'before' => [
                '3rd-middleware-identifier',
            ],
        ],
    ],
];

<?php

return [
    'frontend' => [
        'middleware-identifier' => [
            'after' => [
                'another-middleware-identifier',
            ],
            'before' => [
                '3rd-middleware-identifier',
            ],
        ],
    ],
];

Creating new request / response objects

PSR-17 HTTP Factory interfaces are provided by psr/http-factory and should be used as dependencies for PSR-15 request handlers or services that need to create PSR-7 message objects.

It is discouraged to explicitly create PSR-7 instances of classes from the \TYPO3\CMS\Core\Http namespace (they are not public APIs). Instead, use type declarations against PSR-17 HTTP Message Factory interfaces and dependency injection.

<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Middleware;

use Psr\Http\Message\ResponseFactoryInterface;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\MiddlewareInterface;
use Psr\Http\Server\RequestHandlerInterface;

class StatusCheckMiddleware implements MiddlewareInterface
{
    /** @var ResponseFactoryInterface */
    private $responseFactory;

    public function __construct(ResponseFactoryInterface $responseFactory)
    {
        $this->responseFactory = $responseFactory;
    }

    public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
    {
        if ($request->getRequestTarget() === '/check') {
            $data = ['status' => 'ok'];
            $response = $this->responseFactory->createResponse()
                ->withHeader('Content-Type', 'application/json; charset=utf-8');
            $response->getBody()->write(json_encode($data));
            return $response;
        }
        return $handler->handle($request);
    }
}

Executing HTTP requests in middlewares

The PSR-18 HTTP Client is intended to be used by PSR-15 request handlers in order to perform HTTP requests based on PSR-7 message objects without relying on a specific HTTP client implementation.

PSR-18 consists of a client interface and three exception interfaces:

• \Psr\Http\Client\ClientInterface
• \Psr\Http\Client\ClientExceptionInterface
• \Psr\Http\Client\NetworkExceptionInterface
• \Psr\Http\Client\RequestExceptionInterface

Request handlers use dependency injection to retrieve the concrete implementation of the PSR-18 HTTP client interface \Psr\Http\Client\ClientInterface .

The PSR-18 HTTP Client interface is provided by psr/http-client and may be used as dependency for services in order to perform HTTP requests using PSR-7 request objects. PSR-7 request objects can be created with the PSR-17 Request Factory interface.

<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Middleware;

use Psr\Http\Client\ClientInterface;
use Psr\Http\Message\RequestFactoryInterface;
use Psr\Http\Message\ResponseFactoryInterface;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\MiddlewareInterface;
use Psr\Http\Server\RequestHandlerInterface;

class ExampleMiddleware implements MiddlewareInterface
{
    public function __construct(
        private readonly ResponseFactoryInterface $responseFactory,
        private readonly RequestFactoryInterface $requestFactory,
        private readonly ClientInterface $client,
    ) {}

    public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
    {
        if ($request->getRequestTarget() === '/example') {
            $req = $this->requestFactory->createRequest('GET', 'https://api.external.app/endpoint.json');
            // Perform HTTP request
            $res = $this->client->sendRequest($req);
            // Process data
            $data = [
                'content' => json_decode((string)$res->getBody()),
            ];
            $response = $this->responseFactory->createResponse()
                ->withHeader('Content-Type', 'application/json; charset=utf-8');
            $response->getBody()->write(json_encode($data));
            return $response;
        }
        return $handler->handle($request);
    }
}

Debugging

In order to see which middlewares are configured and to see the order of execution, TYPO3 offers a the menu entry HTTP Middlewares (PSR-15) within the "Configuration" module: