Caching¶

Configuring Cache Engines¶

static Cake\Cache\Cache::config($key, $config = null)¶

Your application can configure any number of ‘engines’ during its bootstrap process. Cache engine configurations are defined in config/app.php.

For optimal performance CakePHP requires two cache engines to be defined.

• _cake_core_ is used for storing file maps, and parsed results of Internationalization & Localization files.

• _cake_model_, is used to store schema descriptions for your applications models.

Using multiple engine configurations also lets you incrementally change the storage as needed. For example in your config/app.php you could put the following:

// ...
'Cache' => [
    'short' => [
        'className' => 'File',
        'duration' => '+1 hours',
        'path' => CACHE,
        'prefix' => 'cake_short_'
    ],
    // Using a fully namespaced name.
    'long' => [
        'className' => 'Cake\Cache\Engine\FileEngine',
        'duration' => '+1 week',
        'probability' => 100,
        'path' => CACHE . 'long' . DS,
    ]
]
// ...

Configuration options can also be provided as a DSN string. This is useful when working with environment variables or PaaS providers:

Cache::config('short', [
    'url' => 'memcached://user:password@cache-host/?timeout=3600&prefix=myapp_',
]);

When using a DSN string you can define any additional parameters/options as query string arguments.

You can also configure Cache engines at runtime:

// Using a short name
Cache::config('short', [
    'className' => 'File',
    'duration' => '+1 hours',
    'path' => CACHE,
    'prefix' => 'cake_short_'
]);

// Using a fully namespaced name.
Cache::config('long', [
    'className' => 'Cake\Cache\Engine\FileEngine',
    'duration' => '+1 week',
    'probability' => 100,
    'path' => CACHE . 'long' . DS,
]);

// Using a constructed object.
$object = new FileEngine($config);
Cache::config('other', $object);

The name of these engine configurations (‘short’ and ‘long’) are used as the $config parameter for Cake\Cache\Cache::write() and Cake\Cache\Cache::read(). When configuring cache engines you can refer to the class name using the following syntaxes:

// Short name (in App\ or Cake namespaces)
Cache::config('long', ['className' => 'File']);

// Plugin short name
Cache::config('long', ['className' => 'MyPlugin.SuperCache']);

// Full namespace
Cache::config('long', ['className' => 'Cake\Cache\Engine\FileEngine']);

// An object implementing CacheEngineInterface
Cache::config('long', ['className' => $myCache]);

Cache::config('redis', [
    'className' => 'Redis',
    'duration' => '+1 hours',
    'prefix' => 'cake_redis_',
    'host' => '127.0.0.1',
    'port' => 6379,
    'fallback' => 'default',
]);

Cache::config('redis', [
    'className' => 'Redis',
    'duration' => '+1 hours',
    'prefix' => 'cake_redis_',
    'host' => '127.0.0.1',
    'port' => 6379,
    'fallback' => false
]);

Writing to a Cache¶

static Cake\Cache\Cache::write($key, $value, $config = 'default')¶

Cache::write() will write a $value to the Cache. You can read or delete this value later by referring to it by $key. You may specify an optional configuration to store the cache in as well. If no $config is specified, default will be used. Cache::write() can store any type of object and is ideal for storing results of model finds:

if (($posts = Cache::read('posts')) === false) {
    $posts = $someService->getAllPosts();
    Cache::write('posts', $posts);
}

Using Cache::write() and Cache::read() to reduce the number of trips made to the database to fetch posts.

$result = Cache::writeMany([
    'article-' . $slug => $article,
    'article-' . $slug . '-comments' => $comments
]);

// $result will contain
['article-first-post' => true, 'article-first-post-comments' => true]

class IssueService
{
    public function allIssues($repo)
    {
        return Cache::remember($repo . '-issues', function () use ($repo) {
            return $this->fetchAll($repo);
        });
    }
}

Reading From a Cache¶

static Cake\Cache\Cache::read($key, $config = 'default')¶

Cache::read() is used to read the cached value stored under $key from the $config. If $config is null the default config will be used. Cache::read() will return the cached value if it is a valid cache or false if the cache has expired or doesn’t exist. The contents of the cache might evaluate false, so make sure you use the strict comparison operators: === or !==.

For example:

$cloud = Cache::read('cloud');
if ($cloud !== false) {
    return $cloud;
}

// Generate cloud data
// ...

// Store data in cache
Cache::write('cloud', $cloud);

return $cloud;

Or if you are using another cache configuration called short, you can specify it in Cache::read() and Cache::write() calls as below:

// Read key "cloud", but from short configuration instead of default
$cloud = Cache::read('cloud', 'short');
if ($cloud !== false) {
    return $cloud;
}

// Generate cloud data
// ...

// Store data in cache, using short cache configuration instead of default
Cache::write('cloud', $cloud, 'short');

return $cloud;

$result = Cache::readMany([
    'article-' . $slug,
    'article-' . $slug . '-comments'
]);
// $result will contain
['article-first-post' => '...', 'article-first-post-comments' => '...']

Deleting From a Cache¶

static Cake\Cache\Cache::delete($key, $config = 'default')¶

Cache::delete() will allow you to completely remove a cached object from the store:

// Remove a key
Cache::delete('my_key');

$result = Cache::deleteMany([
    'article-' . $slug,
    'article-' . $slug . '-comments'
]);
// $result will contain
['article-first-post' => true, 'article-first-post-comments' => true]

Clearing Cached Data¶

static Cake\Cache\Cache::clear($check, $config = 'default')¶

Destroy all cached values for a cache configuration. In engines like: Apcu, Memcached, and Wincache, the cache configuration’s prefix is used to remove cache entries. Make sure that different cache configurations have different prefixes:

// Will only clear expired keys.
Cache::clear(true);

// Will clear all keys.
Cache::clear(false);

static Cake\Cache\Cache::gc($config)¶

Garbage collects entries in the cache configuration. This is primarily used by FileEngine. It should be implemented by any Cache engine that requires manual eviction of cached data.

Using Cache to Store Counters¶

static Cake\Cache\Cache::increment($key, $offset = 1, $config = 'default')¶

static Cake\Cache\Cache::decrement($key, $offset = 1, $config = 'default')¶

Counters in your application are good candidates for storage in a cache. As an example, a simple countdown for remaining ‘slots’ in a contest could be stored in Cache. The Cache class exposes atomic ways to increment/decrement counter values in an easy way. Atomic operations are important for these values as it reduces the risk of contention, and ability for two users to simultaneously lower the value by one, resulting in an incorrect value.

After setting an integer value you can manipulate it using increment() and decrement():

Cache::write('initial_count', 10);

// Later on
Cache::decrement('initial_count');

// Or
Cache::increment('initial_count');

Using Cache to Store Common Query Results¶

You can greatly improve the performance of your application by putting results that infrequently change, or that are subject to heavy reads into the cache. A perfect example of this are the results from Cake\ORM\Table::find(). The Query object allows you to cache results using the cache() method. See the Caching Loaded Results section for more information.

Using Groups¶

Sometimes you will want to mark multiple cache entries to belong to certain group or namespace. This is a common requirement for mass-invalidating keys whenever some information changes that is shared among all entries in the same group. This is possible by declaring the groups in cache configuration:

Cache::config('site_home', [
    'className' => 'Redis',
    'duration' => '+999 days',
    'groups' => ['comment', 'article']
]);

Cake\Cache\Cache::clearGroup($group, $config = 'default')¶

Let’s say you want to store the HTML generated for your homepage in cache, but would also want to automatically invalidate this cache every time a comment or post is added to your database. By adding the groups comment and article, we have effectively tagged any key stored into this cache configuration with both group names.

For instance, whenever a new post is added, we could tell the Cache engine to remove all entries associated to the article group:

// src/Model/Table/ArticlesTable.php
public function afterSave($event, $entity, $options = [])
{
    if ($entity->isNew()) {
        Cache::clearGroup('article', 'site_home');
    }
}

static Cake\Cache\Cache::groupConfigs($group = null)¶

groupConfigs() can be used to retrieve mapping between group and configurations, i.e.: having the same group:

// src/Model/Table/ArticlesTable.php

/**
 * A variation of previous example that clears all Cache configurations
 * having the same group
 */
public function afterSave($event, $entity, $options = [])
{
    if ($entity->isNew()) {
        $configs = Cache::groupConfigs('article');
        foreach ($configs['article'] as $config) {
            Cache::clearGroup('article', $config);
        }
    }
}

Groups are shared across all cache configs using the same engine and same prefix. If you are using groups and want to take advantage of group deletion, choose a common prefix for all your configs.

Globally Enable or Disable Cache¶

static Cake\Cache\Cache::disable¶

You may need to disable all Cache read & writes when trying to figure out cache expiration related issues. You can do this using enable() and disable():

// Disable all cache reads, and cache writes.
Cache::disable();

Once disabled, all reads and writes will return null.

static Cake\Cache\Cache::enable¶

Once disabled, you can use enable() to re-enable caching:

// Re-enable all cache reads, and cache writes.
Cache::enable();

static Cake\Cache\Cache::enabled¶

If you need to check on the state of Cache, you can use enabled().

Creating a Cache Engine¶

You can provide custom Cache engines in App\Cache\Engine as well as in plugins using $plugin\Cache\Engine. Cache engines must be in a cache directory. If you had a cache engine named MyCustomCacheEngine it would be placed in either src/Cache/Engine/MyCustomCacheEngine.php. Or in plugins/MyPlugin/src/Cache/Engine/MyCustomCacheEngine.php as part of a plugin. Cache configs from plugins need to use the plugin dot syntax:

Cache::config('custom', [
    'className' => 'MyPlugin.MyCustomCache',
    // ...
]);

Custom Cache engines must extend Cake\Cache\CacheEngine which defines a number of abstract methods as well as provides a few initialization methods.

The required API for a CacheEngine is

class Cake\Cache\CacheEngine¶

The base class for all cache engines used with Cache.

Cake\Cache\CacheEngine::write($key, $value)¶

Returns:

boolean for success.

Write value for a key into cache, Return true if the data was successfully cached, false on failure.

Cake\Cache\CacheEngine::read($key)¶

Returns:

The cached value or false for failure.

Read a key from the cache. Return false to indicate the entry has expired or does not exist.

Cake\Cache\CacheEngine::delete($key)¶

Returns:

Boolean true on success.

Delete a key from the cache. Return false to indicate that the entry did not exist or could not be deleted.

Cake\Cache\CacheEngine::clear($check)¶

Returns:

Boolean true on success.

Delete all keys from the cache. If $check is true, you should validate that each value is actually expired.

Cake\Cache\CacheEngine::clearGroup($group)¶

Returns:

Boolean true on success.

Delete all keys from the cache belonging to the same group.

Cake\Cache\CacheEngine::decrement($key, $offset = 1)¶

Returns:

Boolean true on success.

Decrement a number under the key and return decremented value

Cake\Cache\CacheEngine::increment($key, $offset = 1)¶

Returns:

Boolean true on success.

Increment a number under the key and return incremented value

Cake\Cache\CacheEngine::gc()¶

Not required, but used to do clean up when resources expire. FileEngine uses this to delete files containing expired content.