--- title: "Caching" manual: "TYPO3 Explained" version: "main" permalink: "https://docs.typo3.org/permalink/t3coreapi:caching@main" source: "ApiOverview/CachingFramework/Index.rst" modified: "2026-09-15T06:32:51+00:00" --- # Caching - [Caching in TYPO3](https://docs.typo3.org/permalink/t3coreapi:caching-in-typo3@main) - [Caching variants - or: what is a "cache hash"?](https://docs.typo3.org/permalink/t3coreapi:caching-variants-or-what-is-a-cache-hash@main) - [Example (excerpt of config/system/additional.php)](https://docs.typo3.org/permalink/t3coreapi:example-excerpt-of-config-system-additional-php@main) - [Clearing/flushing and warming up caches](https://docs.typo3.org/permalink/t3coreapi:clearing-flushing-and-warming-up-caches@main) - [Caching framework](https://docs.typo3.org/permalink/t3coreapi:caching-framework@main) ## Caching in TYPO3 TYPO3 uses multiple caching strategies to ensure fast content delivery. Depending on the content a page contains, TYPO3 chooses the best caching strategy for that use case. For example, you might have a fully-cacheable page, a page that is at least partially cacheable or a page that is completely dynamic. Dynamic elements in TYPO3 are also known as [USER_INT](https://docs.typo3.org/m/typo3/reference-typoscript/main/en-us/ContentObjects/UserAndUserInt/Index.html#cobj-user-int) or [COA_INT](https://docs.typo3.org/m/typo3/reference-typoscript/main/en-us/ContentObjects/CoaAndCoaInt/Index.html#cobj-coa-int) objects - as these are the matching [Typoscript](https://docs.typo3.org/m/typo3/reference-typoscript/main/en-us/Index.html#start) objects used to render non-cacheable content. When visiting a TYPO3 web site, TYPO3 knows the following states: - first time hit, page has never been rendered ("cache miss") - consecutive hit, page has been rendered before ("cache hit") In the first case, TYPO3 renders the complete page and writes cache entries as configured. In the second case, TYPO3 fetches those entries from the cache and delivers them to the user without re-triggering the rendering. In that second case, either the page is fully cached and directly delivered from the cache, or the page has non-cacheable elements on it. If a page has non-cacheable elements, TYPO3 first fetches the cached part of the page and then renders all dynamic parts. > [!NOTE] > The cache contains placeholders for dynamic elements to tell TYPO3 where to > render dynamic parts. > [!TIP] > **Hint** > > For developers: If you are developing a [plugin](https://docs.typo3.org/permalink/t3coreapi:frontend-plugin@main), > think about your plugin's cache lifetime. Ideally, it can be fully cached, > but if not, read the section about the > [caching framework](https://docs.typo3.org/permalink/t3coreapi:caching-architecture@main) to learn how to leverage > TYPO3's caching mechanism to cache your plugin for however long you can - > even 30 seconds might improve performance in some scenarios. ## Caching variants - or: what is a "cache hash"? TYPO3 ideally delivers fully cached pages for maximum performance. However, in scenarios where the same page will deliver different content depending on URL parameters, TYPO3 needs a possibility to identify these "variants" and cache each of them differently. For example, if you have a news plugin and a detail page, the detail page is different for every news entry. To identify the variant, TYPO3 combines a set of parameters and generates a hash value as identifier. These parameters include by default: - `projectPath`: The project path - `id`: The current page ID - `type`: The current page type (`typeNum`) - `groupIds`: The user groups of the logged-in user (if no user is logged in: `0`, `-1` as default values) - `MP`: The [mount point](https://docs.typo3.org/permalink/t3coreapi:mountpoints@main) identifier - `site`: The current [site](https://docs.typo3.org/permalink/t3coreapi:sitehandling@main) and base URL - `staticRouteArguments`: Any route argument configured in the [routing configuration](https://docs.typo3.org/permalink/t3coreapi:routing@main) and resolved in the current [request](https://docs.typo3.org/permalink/t3coreapi:typo3-request@main) - `dynamicArguments`: Any "GET" parameters influencing the rendered page - `sys_template_rows`: The combined contents of all sys_template_records used for this page - `constantConditionList`: constant conditions evaluate for this request - `setupConditionList`: setup conditions evaluated for this request Imagine the following URL `https://example.org/news/?tx_example_news[id]=123` displaying the news with ID `123`. If TYPO3 would cache that page with that parameter without any security mechanisms, it would open a potential denial of service attack as an unlimited amount of cache entries could be generated by adding arbitrary parameters. To avoid that, TYPO3 generates a so-called "cHash" parameter, which is a hash that basically signs the valid parameters for that request. So any parameter that validly influences the rendered page needs to be part of that cHash. With [routing](https://docs.typo3.org/permalink/t3coreapi:routing@main) you can configure TYPO3 not to display the cHash in your URLs in most cases. Routing adds an explicit mapping of incoming readable URL slugs to internal parameter values. This both adds an additional layer for validating slugs as well as reduces the parameters to a limited (and predictable) set of values. Various configuration options exist to configure the cHash behavior via [$GLOBALS\['TYPO3_CONF_VARS'\]\['FE'\]\['cacheHash'\]](https://docs.typo3.org/permalink/t3coreapi:typo3confvars-fe-cachehash@main) in the file `config/system/settings.php` or `config/system/additional.php`: ### cachedParametersWhiteList - **cachedParametersWhiteList** **Only** the given parameters will be evaluated in the cHash calculation. Example: `tx_news_pi1[uid]` > [!WARNING] > **Attention** > > This option will lead to cache calculation being skipped for all > parameters except the ones listed here. Caching of pages will not be > influenced by other parameters beyond the initial caching anymore. ### requireCacheHashPresenceParameters - **requireCacheHashPresenceParameters** Configure parameters that require a cHash. If no cHash is given, but one of the parameters are set, then TYPO3 triggers the configured cHash error behavior ### excludedParameters - **excludedParameters** The given parameters will be ignored in the cHash calculation. Example: `L,tx_search_pi1[query]` ### excludedParametersIfEmpty - **excludedParametersIfEmpty** Configure parameters only being relevant for the cHash if there is an associated value available. Set excludeAllEmptyParameters to true to skip all empty parameters. ### excludeAllEmptyParameters - **excludeAllEmptyParameters** If true, all parameters relevant to cHash are only considered when they are not empty. ### enforceValidation - **enforceValidation** If this option is enabled, the same validation is used to calculate a cHash value as when a valid or invalid "cHash" parameter is given to a request, even when no cHash is given. All properties can be configured with an array of values. Besides exact matches (*equals*) it is possible to apply partial matches at the beginning of a parameter (*startsWith*) or inline occurrences (*contains*). URL parameter names are prefixed with the following indicators: - `=` (*equals*): exact match, default behavior if not given - `^` (*startsWith*): matching the beginning of a parameter name - `~` (*contains*): matching any inline occurrence in a parameter name These indicators can be used for all previously existing sub-properties `cachedParametersWhiteList`, `excludedParameters`, `excludedParametersIfEmpty` and `requireCacheHashPresenceParameters`. The most flexible modification of the page cache parameters is using the [BeforePageCacheIdentifierIsHashedEvent](https://docs.typo3.org/permalink/t3coreapi:beforepagecacheidentifierishashedevent@main) event that allows adding, removing or modifying all parameters. ## Example (excerpt of `config/system/additional.php`) **config/system/additional.php | typo3conf/system/additional.php** ```php $GLOBALS['TYPO3_CONF_VARS']['FE']['cacheHash'] = [ 'excludedParameters' => [ 'utm_source', 'utm_medium', ], 'excludedParametersIfEmpty' => [ '^tx_my_plugin[aspects]', 'tx_my_plugin[filter]', ], ]; ``` For instance instead of having exclude items like **config/system/additional.php | typo3conf/system/additional.php** ```php 'excludedParameters' => [ 'tx_my_plugin[data][uid]', 'tx_my_plugin[data][category]', 'tx_my_plugin[data][order]', 'tx_my_plugin[data][origin]', // ... ], ``` partial matches allow to simplify the configuration and consider all items having `tx_my[data]` (or `tx_my[data][` to be more specific) as prefix like **config/system/additional.php | typo3conf/system/additional.php** ```php 'excludedParameters' => [ '^tx_my_plugin[data][', // ... ], ``` ## Clearing/flushing and warming up caches TYPO3 provides different possibilities to clear all or specific caches. Depending on the context, you might want to - clear the cache for a single page (for example, to make changes visible) - clear the frontend cache (for example, after templating changes) - clear all caches (for example, during development, when making TypoScript changes) - clear all caches incl. [dependency injection](https://docs.typo3.org/permalink/t3coreapi:dependencyinjection@main) (mainly useful during development) Clearing the cache for a single page is done by using the "clear cache button" on that page in the backend (usually visualized with a "bolt" icon). Depending on user rights this option is available for editors. Clearing the frontend caches and all caches can be done via the system toolbar in the TYPO3 backend. This option should only be available to administrators. Clearing all caches can have a significant impact on the performance of the web site and should be used sparingly on production systems. The "fullest" option to clear all caches can be reached via the **System Tools > Maintenance** section. In the development context when new classes have been added to the system or in case of problems with the system using this cache clearing option will clear all caches including compiled code like the dependency injection container. ### Clear cache command In addition to the GUI options explained above, caches can also be cleared via a [CLI command](https://docs.typo3.org/permalink/t3coreapi:symfony-console-commands@main): **Composer-based installation** ```bash vendor/bin/typo3 cache:flush ``` **Classic mode installation (no Composer)** ```bash typo3/sysext/core/bin/typo3 cache:flush ``` Specific cache groups can be defined via the group option. The usage is described as this: ```bash cache:flush [--group ] ``` All available [cache groups](https://docs.typo3.org/permalink/t3coreapi:caching-architecture-core@main) can be supplied as option. The command defaults to flush all available cache groups as the **System Tools > Maintenance** area does. Extensions that register custom caches may listen to the [CacheFlushEvent](https://docs.typo3.org/permalink/t3coreapi:cacheflushevent@main), but usually the cache flush via cache manager groups will suffice to clear those caches, too. ### Cache warmup > [!IMPORTANT] > Cache warm-up fails if the PHP **major or minor** version used by the > CLI differs from the version used by the web server. > (Both numbers are part of the cache key.) > > See [Important: #107649 - Dependency Injection cache is now PHP version dependant](https://docs.typo3.org/c/typo3/cms-core/main/en-us/Changelog/13.4.x/Important-107649-DependencyInjectionCacheIsNowPHPVersionDependant.html#important-107649-1760090777) > for details. It is possible to warmup TYPO3 caches using the command line. The administrator can use the following [CLI command](https://docs.typo3.org/permalink/t3coreapi:symfony-console-commands@main): **Composer-based installation** ```bash vendor/bin/typo3 cache:warmup ``` **Classic mode installation (No Composer)** ```bash typo3/sysext/core/bin/typo3 cache:warmup ``` > [!IMPORTANT] > Cache warming will **not work correctly** if the PHP version used for the > CLI context differs in the major or minor version from the PHP version used for > the web context. Specific cache groups can be defined via the group option. The usage is described as this: ```bash cache:warmup [--group ] ``` All available [cache groups](https://docs.typo3.org/permalink/t3coreapi:caching-architecture-core@main) can be supplied as option. The command defaults to warm all available cache groups. Extensions that register custom caches are encouraged to implement cache warmers via [CacheWarmupEvent](https://docs.typo3.org/permalink/t3coreapi:cachewarmupevent@main). > [!NOTE] > TYPO3 frontend caches will not be warmed by TYPO3 Core, such functionality > could be added by third-party extensions with the help of > [CacheWarmupEvent](https://docs.typo3.org/permalink/t3coreapi:cachewarmupevent@main). ### Use case: deployment It is often required to clear caches during deployment of TYPO3 instance. The integrator may decide to flush all caches or may alternatively flush selected groups (for example, "pages"). It is common practice to clear *all* caches during deployment of a TYPO3 instance update. This means that the first request after a deployment usually takes a major amount of time and blocks other requests due to cache-locks. TYPO3 caches can be warmed during deployment in release preparatory steps in symlink-based deployment/release procedures. This enables fast first requests with all (or at least system) caches being prepared and warmed. Caches are often filesystem relevant (file paths are calculated into cache hashes), therefore cache warmup should only be performed on the the live system, in the *final* folder of a new release, and ideally before switching to that new release (via symlink switch). > [!WARNING] > Caches that have been pre-created on the continuous integration server > will likely be useless as cache hashes will not match (as the final file > system path is relevant to the hash generation). To summarize: Cache warmup is to be used during deployment, on the live system server, inside the new release folder and before switching to the new release. An example deployment could consist of: - Before the release: - git-checkout/rsync your codebase to the continuous integration / build server - `composer install` on the continuous integration / build server - `vendor/bin/typo3 cache:warmup --group system` (*only* on the live system) - Change release symlink to the new release folder - After the release: - `vendor/bin/typo3 cache:flush --group pages` The conceptional idea is to warmup all file-related caches *before* (symlink) switching to a new release and to *only* flush database and frontend (shared) caches after the symlink switch. Database warmup could be implemented with the help of the [CacheWarmupEvent](https://docs.typo3.org/permalink/t3coreapi:cachewarmupevent@main) as an additionally functionality by third-party extensions. Note that file-related caches (summarized into the group "system") can safely be cleared before doing a release switch, as it is recommended to keep file caches per release. In other words, share `var/session/`, `var/log/`, `var/lock/` and `var/charset/` between releases, but keep `var/cache/` be associated only with one release. ## Caching framework TYPO3 contains a data caching framework which supports a wide variety of storage solutions and options for different caching needs. Each cache can be configured individually and can implement its own specific storage strategy. The caching framework exists to help speeding up TYPO3 sites, especially heavily loaded ones. It is possible to move all caches to a dedicated cache server with specialized cache systems like the Redis key-value store (a so called [NoSQL database](https://en.wikipedia.org/wiki/NoSQL)). Major parts of the original caching framework were originally backported from TYPO3 Flow. - [Quick start for integrators](https://docs.typo3.org/permalink/t3coreapi:quick-start-for-integrators@main) - [Configuration](https://docs.typo3.org/permalink/t3coreapi:caching-configuration@main) - [Caching framework architecture](https://docs.typo3.org/permalink/t3coreapi:caching-framework-architecture@main) - [Cache frontends](https://docs.typo3.org/permalink/t3coreapi:cache-frontends@main) - [Cache backends](https://docs.typo3.org/permalink/t3coreapi:cache-backends@main) - [Developer information](https://docs.typo3.org/permalink/t3coreapi:developer-information@main)