Tags

It

As in, “cache it!” This is the main tag you will use when caching dynamic parts of your template.

This method checks if a cached item exists for the current id. If the cached item does not exists, it will process the tagdata (the text between the opening and closing tags), cache it, and return it to the page. If the cached item already exists, it will simply return it (and won’t need to process the tagdata).

Parameters

  • id= (required): The id for the item. If the global="yes" parameter is set, this defaults to "", otherwise it defaults to "item" (the default can be changed on an installation or site-wide basis in your config).
  • for=: The time to live for the cached item either as a timestamp, or as a language string. Here are some valid examples: 45 seconds, 90 sec, 30 minutes, 20 min, 1 hour, 3 hours, 1 day, 7 days, 2 weeks, 2 months, 4 years, 1 year 3 months 2 days 12 hours 10 minutes, 0 (never expires), 1577836800 (a timestamp), {entry_date} (a timestamp variable)
  • seconds=: The time to live for the cached item in seconds. Defaults to 3600 (the default can be changed on an installation or site-wide basis in your config). This parameter will only be used if the for= parameter is left empty.
  • global=: How should the variable be stored? If you want this variable to be unique, and accessible by id throughout all pages of the site, set this to "yes". If you want the variable to be unique only to the current page URL, no action is required, as the default is ("no").
  • drivers=: The driver(s) to use. Can be one or more of the following: "file", "db", "apc", "redis", "sqlite", "memcache", "memcached", or "dummy". APC, Redis, Memcache, and Memcached must (obviously) be installed and configured on your server before they can be used. The default setting (if not specified), is "file" (this default can be changed on a global or site-wide basis in your config). If you want to include additional fallback drivers, simply separate the driver names with a pipe | character (example: "file|db|apc").
  • trim=: If you would like the whitespace at the beginning and end of your tagdata content to be removed, set this to "yes". The default is "no" (this default can be changed on a global or site-wide basis in your config).
  • tags=: You can optionally give an item one or more tags (separate multiple tags with a pipe (|) character. All tags will be converted to lowercase and must be less than 100 characters. In the control panel, you have the ability to clear all items by tag, and to use tags for channel cache breaking.
  • ignore_if_dummy=: When using the dummy driver, it is as if you are not using CE Cache at all; your tagdata will be processed on every page load. If you have really heavy content that you would rather not run if caching is not enabled, set this parameter to "yes", and instead of processing the tag’s tagdata, it will simply return nothing. This tag defaults to "no".
  • url_override=: When caching a non-global (local) item, the page’s URL is automatically determined. If for some reason, you would like to cache the item to a different URL, this parameter will allow you to do so. For example, if your page was store/items/lighting/filter/bulbs, but you did’t want the filter/bulbs to be included, you could override the URL by setting: url_override="store/items/lighting".
  • logged_in_only=: If you would only like this tag to cache if the page visitor is logged-in. The default is "no".
  • logged_out_only=: If you would only like this tag to cache if the page visitor is logged-out. The default is "no".
  • ignore_post_requests=: By default, CE Cache ignores pages requested over POST. If you would like to enable the caching of POST requests, set this to "no". The default is "yes".

Example

{exp:ce_cache:it}
    [...template content to cache goes here...]
{/exp:ce_cache:it}

Note: If you set the for= parameter to "0" (a zero), the data will persist until it is removed manually or otherwise fails to exist.

Escape

Escapes content from being cached. Can be used inside an It or Save tag.

Example

{exp:ce_cache:it}

    [...some heavy content here that will be cached...]

    {!-- Let's escape this conditional, so it's not cached --}
    {exp:ce_cache:escape}
        {if logged_in}
            I'm logged in!!
        {if:else}
            I'm not logged in.
        {/if}
    {/exp:ce_cache:escape}

    [...other content here that will be cached...]

    {!-- This data is dynamic, so let's not cache it. --}
    {exp:ce_cache:escape}
        {exp:ce_str:ing php}
            <?php
               echo date("Y-m-d H:i:s");
           ?>
        {/exp:ce_str:ing}
    {/exp:ce_cache:escape}

    [...more heavy content here to cache...]

{/exp:ce_cache:it}

In the above example, the content inside the exp:ce_cache:escape tags will remain dynamic (it will be run by the EE parser on each page load), even though the surrounding content (the other content inside the it tag) will be cached. This can be a wonderful feature when you want to cache content, but keep some of it dynamic.

Pre-Escaping

If the Escape tag is given a unique tagpart (example: {exp:ce_cache:escape:blah}{/exp:ce_cache:escape:blah} has a unique tagpart of blah) then its tagdata will be pre-escaped (escaped even before segment variables and globals are parsed) when using EE 2.4.0+.

Static

Caches the entire page to a flat file. View the static driver documentation page for more information on static caching.

Parameters

  • for=: The time to live for the cached item either as a timestamp, or as a language string. Here are some valid examples: 45 seconds, 90 sec, 30 minutes, 20 min, 1 hour, 3 hours, 1 day, 7 days, 2 weeks, 2 months, 4 years, 1 year 3 months 2 days 12 hours 10 minutes, 0 (never expires), 1577836800 (a timestamp), {entry_date} (a timestamp variable)
  • seconds=: The time to live for the cached item in seconds. Defaults to 3600 (the default can be changed on an installation or site-wide basis in your config). This parameter will only be used if the for= parameter is left empty.
  • url_override=: The page’s URL is automatically determined. If for some reason, you would like to cache the item to a different URL, this parameter will allow you to do so. For example, if your page was store/items/lighting/filter/bulbs, but you did’t want the filter/bulbs to be included, you could override the URL by setting: url_override="store/items/lighting".
  • tags=: You can optionally give an item one or more tags (separate multiple tags with a pipe (|) character. All tags will be converted to lowercase and must be less than 100 characters. In the control panel, you have the ability to clear all items by tag, and to use tags for channel cache breaking.
  • logged_in_only=: If you would only like this tag to cache if the page visitor is logged-in. The default is "no". For more information, please view the Static Driver Installation instructions tab in the CE Cache control panel page.
  • logged_out_only=: If you would only like this tag to cache if the page visitor is logged-out. The default is "no". For more information, please view the Static Driver Installation instructions tab in the CE Cache control panel page.
  • ignore_post_requests=: By default, CE Cache ignores pages requested over POST. If you would like to enable the caching of POST requests, set this to "no". The default is "yes".

Example

{exp:ce_cache:stat:ic}

Note: If you set the for= parameter to "0" (a zero), the data will persist until it is removed manually or otherwise fails to exist.

Add Tags

Allows one or more tags to be added to a cache item. This is useful when you want to add dynamic content as tags. It will append the new tags to tags set via the tags= parameter, if applicable.

Example

{exp:ce_cache:it tags="test"}
    Tag test.
    {exp:channel:entries channel="blog" limit="1"}
        {exp:ce_cache:add_tag}{url_title}|{entry_id}{/exp:ce_cache:add_tag}
    {/exp:channel:entries}
{/exp:ce_cache:it}
{exp:ce_cache:stat:ic}

In the example above, the It tag is assigned a tag test. Later, when the cache item is being processed, the add_tags method is used to add two more tags to the It tag: the url_title and entry_id of the blog channel entry. Whenever the add_tags tag is used, it will always add the tags to its parent It or Save tag. After the above code is run, the local item will have tags of test, and whatever the url_title, and entry_id tags evaluate to.

The static driver will also be assigned all of the tags that were added via the add_tags method, no matter where they were added in the template. Running the above code would assign the static cache with tags of the channel entry’s url_title and entry_id.

Until

The until tag can be used to alter when the cache item expires. This can be useful, for example, if you have a list of channel entries inside your cache tag and some of them have expiration dates that may be earlier than the cache item's time to live.

To specify an until time, simply pass in a timestamp, or a language string. Here are some examples: 45 seconds, 90 sec, 30 minutes, 20 min, 1 hour, 3 hours, 1 day, 7 days, 2 weeks, 2 months, 4 years, 1 year 3 months 2 days 12 hours 10 minutes, 0 (never expires), 1577836800 (a timestamp), {expiration_date} (a timestamp variable).

Parameters

  • mode=: Determines how to compare the passed-in date to the parent cache-items expiration date. The options are:
    • earliest or e - Will use the earlier of the two dates as the expiration date. This is the default.
    • latest or l - Will use the later of the two dates as the expiration date.
    • force or f - Will always use the until tag's date (assuming it is valid).

Example

{exp:ce_cache:it for="1 week"}
    {exp:channel:entries channel="blog" limit="1"}
        <p>Expiration: {expiration_date} ({expiration_date format="%D, %F %d, %Y - %g:%i:%s"})</p>
        {exp:ce_cache:until}{expiration_date}{/exp:ce_cache:until}
    {/exp:channel:entries}
{/exp:ce_cache:it}

In the example above, the It tag is given an expiration of a week in the future. Later, when the cache item is being processed, the until method is used to potentially override the caches expiration date to the expiration date of the blog entry. If the blog entry expires tomorrow, then the cache item will also expire tomorrow (instead of in a week).

Clear

Manually clears items and/or tags, and optionally refreshes the cleared items.

Parameters

  • items=: You can add items or item parent paths to remove. Items should begin with either global/, local/, or static/, depending on their cache type. If you are specifying a parent path (as opposed to an item id), then be sure to give it a trailing slash (/). Multiple items should be delimited with a pipe (|) character.
  • tags=: In your templates, you can assign tags to the It, Save, and Static methods using the tags= parameter. With this parameter, you can specify one or more tags, and any items that have those tags will be removed. Multiple tags should be delimited with a pipe (|) character.
  • refresh=: You can choose to have cache items recreate themselves after they are removed. In order to allow the items to refresh after they are cleared, please specify the number of seconds to wait between refreshing cached items. To have all items attempt to refresh at one time (not recommended), you could specify 0 (zero). By default, the cleared cache items are not refreshed.

Examples

  • To clear all static items for the entire site, you would add: items="static/"
  • If you had a “blog” section of your site, and wanted to remove all local cached content under that section, you would add: items="local/blog/"
  • If you wanted to clear a specific item, like your home page, you could add: items="local/item" (assuming your home page has a cache item with the default id “item”)
  • To clear a global item with an id of “footer”, you could add: items="global/footer"
  • To clear all local caches where {segment_1} matched the current {channel_name} and {segment_2} matched the {url_title}, use items="local/{channel_name}/{url_title}/"
  • To clear all items with a tag of “apple”, you would specify tags="apple"
  • To clear all items with a tag of the current channel name, you could specify tags="{channel_name}"
{exp:ce_cache:clear items="local/blog/|global/footer" tags="portfolio|blueberry|tuesday" refresh="5"}

The above example would clear all local (non-global) cache items that begin with “blog/” (again, the trailing slash works as a wildcard to clear all child entries), and a global item with an id of “footer”. Additionally, all cache items that are tagged with “portfolio”, “blueberry”, or “tuesday” would be cleared. All non-global items would also be refreshed with a 5 second interval between each refresh request.

Note: The items= and tags= parameters are not both required, but one (or both) of them should be specified (otherwise there would be nothing to clear…).

Note: Tags are not case sensitive, so tags="apple" is considered the same as tags="Apple". Although discouraged, spaces in your tags are allowed, so tags="bricks in the wall" is technically a valid tag. Tags may not contain any pipe (|) characters, as the pipe character is used to separate multiple tags.

Note: Cache refreshing will only work for local (non-global) items, as they contain a relative path to a specific page. However, any removed global items that happen to be on a refreshed page will also be recreated. No refreshing will happen by default.

Note: Using a refresh delay can be really helpful if you are refreshing a large number of pages, and you don’t want to bog down your server all at one time. Keep in mind that this will take more time; if you have 200 pages with items to be refreshed, and you are delaying 2 seconds between each one, it will take at least 400 seconds (almost 7 minutes) for all of the cache items to be recreated.

Save

Cache an item by id.

Parameters

  • id= (required): The id for the item. If the global="yes" parameter is set, this defaults to "", otherwise it defaults to "item" (the default can be changed on an installation or site-wide basis in your config).
  • for=: The time to live for the cached item either as a timestamp, or as a language string. Here are some valid examples: 45 seconds, 90 sec, 30 minutes, 20 min, 1 hour, 3 hours, 1 day, 7 days, 2 weeks, 2 months, 4 years, 1 year 3 months 2 days 12 hours 10 minutes, 0 (never expires), 1577836800 (a timestamp), {entry_date} (a timestamp variable)
  • seconds=: The time to live for the cached item in seconds. Defaults to 3600 (the default can be changed on an installation or site-wide basis in your config). This parameter will only be used if the for= parameter is left empty.
  • global=: How should the variable be stored? If you want this variable to be unique, and accessible by id throughout all pages of the site, set this to "yes". If you want the variable to be unique only to the current page URL, no action is required, as the default is ("no").
  • show=: Do you want the data to be returned to the template? Can be "yes" or "no". Defaults to "no".
  • drivers=: The driver(s) to use. Can be one or more of the following: "file", "db", "apc", "redis", "sqlite", "memcache", "memcached", or "dummy". APC, Redis, Memcache, and Memcached must (obviously) be installed and configured on your server before they can be used. The default setting (if not specified), is "file" (this default can be changed on a global or site-wide basis in your config). If you want to include additional fallback drivers, simply separate the driver names with a pipe | character (example: "file|db|apc").
  • trim=: If you would like the whitespace at the beginning and end of your tagdata content to be removed, set this to "yes". The default is "no" (this default can be changed on a global or site-wide basis in your config).
  • tags=: You can optionally give an item one or more tags (separate multiple tags with a pipe (|) character. All tags will be converted to lowercase and must be less than 100 characters. In the control panel, you have the ability to clear all items by tag, and to use tags for channel cache breaking.
  • ignore_if_dummy=: When using the dummy driver, it is as if you are not using CE Cache at all; your tagdata will be processed on every page load. If you have really heavy content that you would rather not run if caching is not enabled, set this parameter to "yes", and instead of processing the tag’s tagdata, it will simply return nothing. This tag defaults to "no".
  • url_override=: When caching a non-global (local) item, the page’s URL is automatically determined. If for some reason, you would like to cache the item to a different URL, this parameter will allow you to do so. For example, if your page was store/items/lighting/filter/bulbs, but you did’t want the filter/bulbs to be included, you could override the URL by setting: url_override="store/items/lighting".
  • logged_in_only=: If you would only like this tag to cache if the page visitor is logged-in. The default is "no".
  • logged_out_only=: If you would only like this tag to cache if the page visitor is logged-out. The default is "no".
  • ignore_post_requests=: By default, CE Cache ignores pages requested over POST. If you would like to enable the caching of POST requests, set this to "no". The default is "yes".

Example

{exp:ce_cache:save}
    [...template content to cache goes here...]
{/exp:ce_cache:save}

Note: If you set the for= parameter to "0" (a zero), the data will persist until it is removed manually or otherwise fails to exist.

Get

Get an item from the cache by id.

Parameters

  • id= (required): The id for the item. If the global="yes" parameter is set, this defaults to "", otherwise it defaults to "item" (the default can be changed on an installation or site-wide basis in your config).
  • global=: If you are retrieving a global item by id, set to "yes". If you're requesting a page specific item, there is no need to include this parameter, as it defaults to "no".
  • drivers=: The driver(s) to use. Can be one or more of the following: "file", "db", "apc", "redis", "sqlite", "memcache", "memcached", or "dummy". APC, Redis, Memcache, and Memcached must (obviously) be installed and configured on your server before they can be used. The default setting (if not specified), is "file" (this default can be changed on a global or site-wide basis in your config). If you want to include additional fallback drivers, simply separate the driver names with a pipe | character (example: "file|db|apc").
  • url_override=: When caching a non-global (local) item, the page’s URL is automatically determined. If for some reason, you would like to cache the item to a different URL, this parameter will allow you to do so. For example, if your page was store/items/lighting/filter/bulbs, but you did’t want the filter/bulbs to be included, you could override the URL by setting: url_override="store/items/lighting".

Example

{exp:ce_cache:get id="test"}

Note: If you are getting a variable that was saved (via the It or Save tag) with a parameter of global="yes", be sure to get that variable with the same parameter. Likewise, the adapter should also coincide with the one used to set the cache.

Delete

Delete an item from the cache.

Parameters

  • id= (required): The id for the item. If the global="yes" parameter is set, this defaults to "", otherwise it defaults to "item" (the default can be changed on an installation or site-wide basis in your config).
  • global=: If you are retrieving a global item by id, set to "yes". If you’re requesting a page specific item, there is no need to include this parameter, as it defaults to "no".
  • drivers=: The driver(s) to use. Can be one or more of the following: "file", "db", "apc", "redis", "sqlite", "memcache", "memcached", or "dummy". APC, Redis, Memcache, and Memcached must (obviously) be installed and configured on your server before they can be used. The default setting (if not specified), is "file" (this default can be changed on a global or site-wide basis in your config). If you want to include additional fallback drivers, simply separate the driver names with a pipe | character (example: "file|db|apc").
  • url_override=: When caching a non-global (local) item, the page’s URL is automatically determined. If for some reason, you would like to cache the item to a different URL, this parameter will allow you to do so. For example, if your page was store/items/lighting/filter/bulbs, but you did’t want the filter/bulbs to be included, you could override the URL by setting: url_override="store/items/lighting".

Example

{exp:ce_cache:delete id="test"}

Note: If you are deleting a variable that was saved (via the It or Save tag) with a parameter of global="yes", be sure to use the same parameter when trying to delete it. Likewise, the adapter should also coincide with the one used to set the cache.

Get Metadata

Get information about a cached item.

Parameters

  • id= (required): The id for the item. If the global="yes" parameter is set, this defaults to "", otherwise it defaults to "item" (the default can be changed on an installation or site-wide basis in your config).
  • global=: If you are retrieving a global item by id, set to "yes". If you’re requesting a page specific item, there is no need to include this parameter, as it defaults to "no".
  • drivers=: The driver(s) to use. Can be one or more of the following: "file", "db", "apc", "redis", "sqlite", "memcache", "memcached", or "dummy". APC, Redis, Memcache, and Memcached must (obviously) be installed and configured on your server before they can be used. The default setting (if not specified), is "file" (this default can be changed on a global or site-wide basis in your config). If you want to include additional fallback drivers, simply separate the driver names with a pipe | character (example: "file|db|apc").
  • url_override=: When caching a non-global (local) item, the page’s URL is automatically determined. If for some reason, you would like to cache the item to a different URL, this parameter will allow you to do so. For example, if your page was store/items/lighting/filter/bulbs, but you did’t want the filter/bulbs to be included, you could override the URL by setting: url_override="store/items/lighting".

Example

{exp:ce_cache:get_metadata id="test"}
    <p>Expires: {expiry format="%D, %F %d, %Y - %g:%i:%s"}</p>
    <p>Made: {made format="%D, %F %d, %Y - %g:%i:%s"}</p>
    <p>Initial Time To Live: {ttl} seconds</p>
    <p>Remaining Time To Live: {ttl_remaining} seconds</p>
    <p>File size: {size}</p>
    <p>Raw file size: {size_raw} bytes</p>
{/exp:ce_cache:get_metadata}

Note: If you are getting a variable that was saved (via the It or Save tag) with a parameter of global="yes", be sure to get that variable with the same parameter. Likewise, the adapter should also coincide with the one used to set the cache.

Clean

Purges the cache for all of the specified drivers.

Parameters

  • drivers=: The driver(s) to use. Can be one or more of the following: "file", "db", "static", "apc", "redis", "sqlite", "memcache", "memcached", or "dummy". Static, APC, Redis, Memcache, and Memcached must (obviously) be installed and configured on your server before they can be used. The default setting (if not specified), is "file" (this default can be changed on a global or site-wide basis in your config). If you want to include additional fallback drivers, simply separate the driver names with a pipe | character (example: "file|db|apc").
  • site_only=: This tag cleans the current site’s cache for each of the specified drivers. To clear the entire cache for each of the drivers (not just for the current site), set site_only="no". The default for this setting is "yes".
  • force=: If not set to"no", the tag will be run even if caching is disabled, or if any of the other conditionals that may normally prevent caching are present. Forcing the cache to be cleared no matter what can be useful for many reasons; like hitting the URL of a template that contains this tag after a git deployment. The value of this parameter can be set to "yes" or "no". The default is "yes".

Example

{exp:ce_cache:clean}

Note: You can also clear the cache for each supported driver from the [CE Cache Control Panel page](/user-guide/control-panel.html#clear_cache).

Is Supported

Returns whether or not a driver is supported. Is intended to be used in a conditional.

Example

<!-- 'file' should be supported as long as PHP has adequate read/write abilities on your server -->
<p>File-based caching {if {exp:ce_cache:is_supported driver="file"} }is{if:else}is not{/if} supported.</p>

<!-- 'db' should always be supported -->
<p>Database caching {if {exp:ce_cache:is_supported driver="db"} }is{if:else}is not{/if} supported.</p>

<!-- 'dummy' should always be supported -->
<p>Dummy caching {if {exp:ce_cache:is_supported driver="dummy"} }is{if:else}is not{/if} supported.</p>

<!-- 'static', 'apc', 'redis', 'memcache', and/or 'memcached' have to be installed and configured on your server in order for their respective drivers to work -->
<p>APC {if {exp:ce_cache:is_supported driver="apc"} }is{if:else}is not{/if} supported.</p>
<p>Redis {if {exp:ce_cache:is_supported driver="redis"} }is{if:else}is not{/if} supported.</p>
<p>SQLite {if {exp:ce_cache:is_supported driver="sqlite"} }is{if:else}is not{/if} supported.</p>
<p>Memcache {if {exp:ce_cache:is_supported driver="memcache"} }is{if:else}is not{/if} supported.</p>
<p>Memcached {if {exp:ce_cache:is_supported driver="memcached"} }is{if:else}is not{/if} supported.</p>
<p>Static {if {exp:ce_cache:is_supported driver="static"} }is{if:else}is not{/if} supported.</p>