ReStructured Text InfrastructureTYPO3 CMS - What's Newwiki.typo3.orgTYPO3 CMS Documentation

Feature #34307

Add documentation for stdWrap function "cache"

Added by Tolleiv Nietsch about 5 years ago. Updated about 5 years ago.

Should have
Target version:
Start date:
Due date:
% Done:



The stdWrap options to store and read data from the cachingframework will be added within #34299

The commit message already gives a good explaination:

  • Cacheable content is always page specific.
    Pages cannot share cached content.
  • Cacheable content has no individual lifetime
    but is bound to the lifetime of the page where it is placed.

Introduce new configuration options that will store the
content into the caching framework:

5 = TEXT
5 {
cache.key = mycurrenttimestamp
cache.tags = tag_a,tag_b,tag_c
cache.lifetime = 3600
data = date : U
strftime = %H:%M:%S

or (for page specific cache that doesn't take
other parameters into account)
5 = TEXT
5 {
cache.key = mycurrenttimestamp_{page:id}
cache.key.insertData = 1

See details on

Related issues

Related to Core - Bug #34299: stdWrap caching Resolved 2012-02-26
Related to Core - Bug #49329: Content caching with page data key not working Closed 2013-06-21


#1 Updated by Fabrizio Branca about 5 years ago


This feature comes with three configuration options in stdWrap:

  • cache.key, Type: string/stdWrap, (must be a valid cache identifier)
  • cache.lifetime, Type: "infinite", "default" or <int> (with stdWrap support)
  • cache.tags, Type: string/stdWrap (comma-separated list of strings)

How it works

The presence of the cache.key will trigger this feature. Actually it will be evaluated twice during stdWrap content rendering.

  • The very first thing stdWrap does (only the stdWrapPreProcess comes even before that) is to evaluate if the there is a cache entry for the given cache.key. If there is one, stdWrap processing will be stopped and the cached content will be returned. If no cache content is found for this cache.key the stdWrap processing continuos as usual.
  • At the very end of the rendering (only the stdWrapPostProcess and the debug* functions will be executed) the rendered content will be stored into the cache if a cache.key was set. The configuration options cache.tags and cache.lifetime allow to control the caching.

HINT: This feature relies on the caching framework. In TYPO3 version < 4.6 the caching framework needs to be enabled for this feature to work. Otherwise content will simply not be cached, but rendered on every call.

HINT: Please take into account in which order stdWrap is processed for your current cObject and what content is processed/generated inside that stdWrap. E.g. using TEXT cObjects works perfectly, while using stdWrap on COA or HMENU will be processed after the inside content is rendered. In latter case caching is not efficient at all, as the content will be rendered anyways. In those case you can still nest your inside an outer stdWrap to gain the same effect:


5 = TEXT
5 {
  cache.key = mycachedcoa
  cObject = COA
  cObject {
    10 = ...

This nesting also allows you to cache USER and USER_INT output, where no stdWrap is available by default.

Configuration options


The cache key is the cache identifier that is used to store the rendered content into the cache or to read it from there. The cache_hash storage will be used. It is the reponsibility of the developer to choose a cache-key that is accurate enough to distinguish different versions of the rendered content will being generic enough to stay efficient.

Example 1: (fixed key)

5 = TEXT
5 {
  cache.key = mycachedcontent
  data = date : U
  strftime = %H:%M:%S

The cached content is the same for all pages and all cached versions of the pages, regardless of any conditions, parameters or whatever would be used to create different cached content. This might be useful for caching a box with latest news that is visible on all pages.

Example 2: (dynamic key using page id)

cache.key = mycachedcontent_{page:id}
cache.key.insertData = 1

The cached content is page specific, but does not take any other parameters into account. This can be used for cache the menu on single view pages. While every displayed item on that single view page will trigger a new cache page, the menu is not affected from this and might only depend on the current page id.

Example 3: (dynamic key using page id and language uid)

cache.key = mycachedcontent_{page:id}_{TSFE:sys_language_uid}
cache.key.insertData = 1

Same as example 2 only also taking the language into account.


Stored content can have its individual cache lifetime and is not bound to the page where it is displayed.
The cache.lifetime parameter can have following values
- "infinite": cached content will not expire unless actively purged by id or by tag or if the complete cache is flushed
- "default": default cache lifetime configured in config.cache_period is used
- <int>: lifetime in seconds

HINT: Using this cache content wrapped in a _INT (e.g. USER_INT, COA_INT) can be cached aswell as content from cacheable cObjects (e.g TEXT, COA,...).
While content wrapped in a _INT cObject will still be cached by this features it will be checked everytime it is requested. From TYPO3's perspective it is usual uncached content that will be replaced inserted as a placeholder and replaced on every page request - with the only difference that it might respond way faster as it will be loaded from cache internally.
Cached content wrapped in a cacheable cObject (e.g. TEXT, COA,...) will additionally be stored into the page cache as part of the page. If the page's cache lifetime is longer than the lifetime of the double cached stdWrap content the page might show outdated content for the stdWrap content as it will not be try to regenerate it until the page's cache expires. (Watch out for hooks in tslib_content->stdWrap_cacheStore() and tslib_fe->get_cache_timeout() that allow fine-grained control over this behaviour.)


This configuration can hold a comma-separated list of tags. Those tags will be attached to the stored cached content into the cache_hash storage (not into cache_pages) and can be used to purge the cached content.

#2 Updated by Chris topher about 5 years ago

  • Assignee set to Chris topher

Whoah, what a documentation. :-)

The documentation belongs in the table with all the stdWrap properties in their order of execution. However, the "cache" function is used at two places:
  • First at the very beginning, directly after the first hook. This only is a reading of what is in cache. You cannot influence the caching action itself there.
  • And then it is used at the very end, directly before the last hook. This is also the point where all the options are checked. Depending on what is set at that point, writing to the cache happens with the according settings (or does not). I therefore documented "cache" at that place.
Some notes:
  • If the lifetime should be infinite, the value for cache.lifetime is not "infinite" as written above, but "unlimited".
  • I have not added the details about the benefits of caching objects separately from pages. Also the details about caching *_INT objects are not included as this would have made the documentation rather long and more is a howto, which we usually do not have in TSref. This makes these aspects ideal candidates for a post on or so.

#3 Updated by Chris topher about 5 years ago

  • Subject changed from Add documentation for stdWrap cacheStore / cacheRead to Add documentation for stdWrap function "cache"
  • Status changed from New to Resolved
  • % Done changed from 0 to 100

Committed in r1175.

#4 Updated by Francois Suter about 5 years ago

I'm a bit embarrassed about the note relating "TYPO3 4.5", since this is a TYPO3 4.7 feature. It has been pushed as a candidate for backports to 4.6 and 4.5, but it's not been committed yet. I would remove this note until it's really back-ported. We can always put it back in an update to the documentation. Anyway we would need to specify since which particular minor version it is available.

#5 Updated by Chris topher about 5 years ago

Francois Suter wrote:

(...) I would remove this note until it's really back-ported.

Oh, you're right. I had only seen the three branches and thought it was already integrated everywhere.

I have reformulated this note as part of r1192 and removed the version number out of the statement.

#6 Updated by Chris topher about 5 years ago

  • Status changed from Resolved to Closed

Also available in: Atom PDF