Developer information

This chapter is aimed at extension authors who want to use the caching framework for their needs. It is about how to use the framework properly. For details about its inner working, please refer to the section about architecture.

Example usages can be found throughout the TYPO3 Core, in particular in the system extensions core and extbase.

Cache registration

Registration of a new cache should be done in an extension's ext_localconf.php. The example below defines an empty sub-array in cacheConfigurations. Neither frontend nor backend are defined: The cache manager will choose the default variable frontend and the database backend by default.

EXT:my_extension/ext_localconf.php

<?php

$GLOBALS['TYPO3_CONF_VARS']['SYS']['caching']['cacheConfigurations']['myext_mycache']
    ??= [];

Tip

The null coalescing assignment operator (??=) check is used to enable administrators to overwrite configuration of caches in config/system/settings.php. During bootstrap, any ext_localconf.php is loaded after config/system/settings.php and config/system/additional.php are loaded, so it is important to make sure that the administrator did not already set any configuration of the extension's cache.

If special settings are needed, for example, a specific backend (like the transient memory backend), it can be defined with an additional line below the cache array declaration. The extension documentation should hint an integrator about specific caching needs or setups in this case.

Tip

Extensions should not force specific settings, therefore the null coalescing assignment operator (??=) is used to allow administrators to overwrite those settings. It is recommended to set up a cache configuration with sane defaults, but administrators should always be able to overwrite them for whatever reason.

EXT:my_extension/ext_localconf.php

<?php

declare(strict_types=1);

use TYPO3\CMS\Core\Cache\Backend\TransientMemoryBackend;

defined('TYPO3') or die();

$GLOBALS['TYPO3_CONF_VARS']['SYS']['caching']['cacheConfigurations']['myext_mycache']
    ??= [];
$GLOBALS['TYPO3_CONF_VARS']['SYS']['caching']['cacheConfigurations']['myext_mycache']['backend']
    ??= TransientMemoryBackend::class;

Using the cache

First, we need to prepare the injection of our cache by setting it up as service in the container service configuration:

EXT:my_extension/Configuration/Services.yaml

services:
  # Place here the default dependency injection configuration

  cache.myext_mycache:
    class: TYPO3\CMS\Core\Cache\Frontend\FrontendInterface
    factory: ['@TYPO3\CMS\Core\Cache\CacheManager', 'getCache']
    arguments: ['myext_mycache']

Read how to configure dependency injection in extensions.

The name of the service for the injection configuration is cache.myext_mycache, the name of the cache is myext_mycache (as defined in ext_localconf.php). Both can be anything you like, just make sure they are unique and clearly hint at the purpose of your cache.

Here is some example code which retrieves the cache via dependency injection:

EXT:my_extension/Classes/MyClass.php

<?php

namespace MyVendor\MyExtension;

use TYPO3\CMS\Core\Cache\Frontend\FrontendInterface;

final class MyClass
{
    public function __construct(
        private readonly FrontendInterface $cache,
    ) {}

    //...

    private function getCachedValue(string $cacheIdentifier, array $tags, int|null $lifetime): array
    {
        // If value is false, it has not been cached
        $value = $this->cache->get($cacheIdentifier);
        if ($value === false) {
            // Store the data in cache
            $value = $this->calculateData();
            $this->cache->set($cacheIdentifier, $value, $tags, $lifetime);
        }

        return $value;
    }

    private function calculateData(): array
    {
        $data = [];
        // todo: implement
        return $data;
    }
}

Tip

It is not needed to call $this->cache->has() before accessing cache entries with $this->cache->get() as the latter returns false if no entry exists.

Since the auto-wiring feature of the dependency injection container cannot detect which cache configuration should be used for the $cache argument of MyClass, the container service configuration needs to be extended:

EXT:my_extension/Configuration/Services.yaml

services:
  # Place here the default dependency injection configuration
  # and the configuration of the cache from above

  MyVendor\MyExtension\MyClass:
    arguments:
      $cache: '@cache.myext_mycache'

Read how to configure dependency injection in extensions.

Here @cache.myext_mycache refers to the cache service we defined above. This setup allows you to freely inject the very same cache into any class.

Note

After changes in the Configuration/Services.yaml file flush the cache via Admin Tools > Maintenance or the CLI command cache:flush:

vendor/bin/typo3 cache:flush

typo3/sysext/core/bin/typo3 cache:flush

Working with cache tags

The frontend cache collector API is available as a PSR-7 request attribute to collect cache tags and their corresponding lifetime. Find more information in the chapter Frontend cache collector.