ModifyClearCacheActionsEvent 

Changed in version 14.3

The CacheAction array key href used in cache action definitions provided via the ModifyClearCacheActionsEvent has been deprecated in favor of endpoint. The new key name better reflects the purpose of this field, which is used as an AJAX endpoint URL. The value must be a string. See Migration.

The PSR-14 event \TYPO3\CMS\Backend\Backend\Event\ModifyClearCacheActionsEvent is fired in the ClearCacheToolbarItem class and allows extension authors to modify the clear cache actions, shown in the TYPO3 backend top toolbar.

The event can be used to change or remove existing clear cache actions, as well as to add new actions. Therefore, the event also contains, next to the usual "getter" and "setter" methods, the convenience method add() for the cacheActions and cacheActionIdentifiers arrays.

Example 

EXT:my_extension/Classes/Backend/EventListener/MyEventListener.php 
<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Backend\EventListener;

use TYPO3\CMS\Backend\Backend\Event\ModifyClearCacheActionsEvent;
use TYPO3\CMS\Backend\Routing\UriBuilder;
use TYPO3\CMS\Core\Attribute\AsEventListener;

#[AsEventListener(
    identifier: 'my-extension/toolbar/my-event-listener',
)]
final readonly class MyEventListener
{
    public function __construct(private UriBuilder $uriBuilder) {}

    public function __invoke(ModifyClearCacheActionsEvent $event): void
    {
        $event->addCacheAction([
            // Required keys:
            'id' => 'pages',
            'title' => 'core.cache:group.pages.label',
            'endpoint' => (string)$this->uriBuilder->buildUriFromRoute(
                'tce_db',
                ['cacheCmd' => 'pages'],
            ),
            'iconIdentifier' => 'actions-system-cache-clear-impact-low',
            // Optional, recommended keys:
            'description' => 'core.cache:group.pages.description',
            'severity' => 'success',
        ]);
    }
}
Copied!

The response returned by the AJAX endpoint should look like this:

use TYPO3\CMS\Core\Http\JsonResponse;

// Success
return new JsonResponse([
    'success' => true,
    'title'   => $languageService->sL('myext.messages:notification.success.title'),
    'message' => $languageService->sL('myext.messages:notification.success.message'),
]);

// Failure
return new JsonResponse([
    'success' => false,
    'title'   => $languageService->sL('myext.messages:notification.error.title'),
    'message' => $languageService->sL('myext.messages:notification.error.message'),
]);
Copied!

API 

class ModifyClearCacheActionsEvent
Fully qualified name
\TYPO3\CMS\Backend\Backend\Event\ModifyClearCacheActionsEvent

An event to modify the clear cache actions, shown in the TYPO3 Backend top toolbar

addCacheAction ( array $cacheAction)
param $cacheAction

the cacheAction

setCacheActions ( array $cacheActions)
param $cacheActions

the cacheActions

getCacheActions ( )
Returns
list<CacheAction>
addCacheActionIdentifier ( string $cacheActionIdentifier)
param $cacheActionIdentifier

the cacheActionIdentifier

setCacheActionIdentifiers ( array $cacheActionIdentifiers)
param $cacheActionIdentifiers

the cacheActionIdentifiers

getCacheActionIdentifiers ( )
Returns
list<non-empty-string>

addCacheAction 

The cache action array element consists of the following keys and values:

id

id
Type
string
Required

true

Contains an existing cache id like pages or all or one registered via the addCacheActionIdentifier.

title

title
Type
string or LLL reference
Required

true

The title displayed in the clear cache menu.

endpoint

endpoint
Type
string
Required

true

The AJAX endpoint. AJAX endpoints registered as custom cache actions via ModifyClearCacheActionsEvent should return a JSON response containing success, title, and message fields.

The clear-cache toolbar treats a missing or non- false success value as a successful operation and falls back to generic notification labels when title or message are absent. Providing explicit values, however, gives users meaningful, context-specific feedback and ensures error conditions are surfaced correctly.

iconIdentifier

iconIdentifier
Type
string
Required

true

An icon to be displayed in the clear cache menu

description

description
Type
string or LLL reference

The description displayed in the clear cache menu.

severity

severity
Type
string or LLL reference

The key severity can contain one of these strings: notice, info, success, warning, error.

Example cache action array 
$event->addCacheAction([
    // Required keys:
    'id' => 'pages',
    'title' => 'core.cache:group.pages.label',
    'endpoint' => (string)$uriBuilder->buildUriFromRoute('tce_db', ['cacheCmd' => 'pages']),
    'iconIdentifier' => 'actions-system-cache-clear-impact-low',
    // Optional, recommended keys:
    'description' => 'core.cache:group.pages.description',
    'severity' => 'success',
]);
Copied!

addCacheActionIdentifier 

The cache identifier array is a numerical array in which the array value corresponds to the registered id of the cache action array. Here is an example of how to use it for a custom cache action:

Example cache action array combined with a cache identifier array 
$myIdentifier = 'myExtensionCustomStorageCache';
$event->addCacheAction([
    'id' => $myIdentifier,
    'title' => 'my_extension.cache:label',
    // Note to register your own route, this is an example
    'endpoint' => (string)$uriBuilder->buildUriFromRoute('ajax_' . $myIdentifier . '_purge'),
    'iconIdentifier' => 'actions-system-cache-clear-impact-low',
    'description' => 'my_extension.cache:description',
    'severity' => 'notice',
]);
$event->addCacheActionIdentifier($myIdentifier);
Copied!

Migration: replace key href with key endpoint 

When dropping TYPO3 v13 support replace the href key with endpoint in any CacheAction array returned from a ModifyClearCacheActionsEvent listener:

$event->addCacheAction([
    'id' => 'my_custom_cache',
-   'href' => $uriBuilder->buildUriFromRoute('ajax_my_cache_clear'),
+   'endpoint' => (string)$uriBuilder->buildUriFromRoute('ajax_my_cache_clear'),
    'iconIdentifier' => 'actions-system-cache-clear',
    'title' => 'Clear my cache',
    'description' => 'Optional description',
    'severity' => 'notice',
]);
Copied!