Frontend cache instruction

New in version 13.0

This request attribute is a replacement for the now internal TypoScriptFrontendController->no_cache property.

The frontend.cache.instruction frontend request attribute can be used by middlewares to disable cache mechanics of frontend rendering.

In early middlewares before typo3/cms-frontend/tsfe, the attribute may or may not exist already. A safe way to interact with it is like this:

EXT:my_extension/Classes/Middleware/MyEarlyMiddleware.php

<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Middleware;

use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\MiddlewareInterface;
use Psr\Http\Server\RequestHandlerInterface;
use TYPO3\CMS\Frontend\Cache\CacheInstruction;

final class MyEarlyMiddleware implements MiddlewareInterface
{
    public function process(
        ServerRequestInterface $request,
        RequestHandlerInterface $handler,
    ): ResponseInterface {
        // Get the attribute, if not available, use a new CacheInstruction object
        $cacheInstruction = $request->getAttribute(
            'frontend.cache.instruction',
            new CacheInstruction(),
        );

        // Disable the cache and give a reason
        $cacheInstruction->disableCache('EXT:my-extension: My-reason disables caches.');

        // Write back the cache instruction to the attribute
        $request = $request->withAttribute('frontend.cache.instruction', $cacheInstruction);

        // ... more logic

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

Extension with middlewares or other code after typo3/cms-frontend/tsfe can assume the attribute to be set already. Usage example:

EXT:my_extension/Classes/Middleware/MyLaterMiddleware.php

<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Middleware;

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

final class MyLaterMiddleware implements MiddlewareInterface
{
    public function process(
        ServerRequestInterface $request,
        RequestHandlerInterface $handler,
    ): ResponseInterface {
        // Get the attribute
        $cacheInstruction = $request->getAttribute('frontend.cache.instruction');

        // Disable the cache and give a reason
        $cacheInstruction->disableCache('EXT:my-extension: My-reason disables caches.');

        // ... more logic

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

API

class CacheInstruction

Fully qualified name: \TYPO3\CMS\Frontend\Cache\CacheInstruction

This class contains cache details and is created or updated in middlewares of the Frontend rendering chain and added as Request attribute "frontend.cache.instruction".

Its main goal is to disable the Frontend cache mechanisms in various scenarios, for instance when the admin panel is used to simulate access times, or when security mechanisms like cHash evaluation do not match.

disableCache ( string $reason)

Instruct the core Frontend rendering to disable Frontend caching. Extensions with custom middlewares may set this.

Note multiple cache layers are involved during Frontend rendering: For instance multiple TypoScript layers, the page cache and potentially others. Those caches are read from and written to within various middlewares. Depending on the position of a call to this method within the middleware stack, it can happen that some or all caches have already been read of written.

Extensions that use this method should keep an eye on their middleware positions in the stack to estimate the performance impact of this call. It's of course best to not use the 'disable cache' mechanic at all, but to handle caching properly in extensions.

param $reason: the reason

isCachingAllowed ( )

Returns: bool