---
title: "Cache"
version: "5.19"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.phalcon.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Cache

## Overview

The [Phalcon\Cache\Cache][cache-cache] is a component that offers a lightweight yet flexible caching mechanism to be used with your Phalcon applications.

Frequently used data or already processed/calculated data, can be stored in a cache storage for easier and faster retrieval. Since [Phalcon\Cache\Cache][cache-cache] is written in Zephir, and therefore compiled as C code, it can achieve higher performance while reducing the overhead that comes with getting data from any storage container. Some examples that warrant the use of a cache are:

* You are making complex calculations and the output does not change frequently
* You are producing HTML using the same data all the time (same HTML)
* You are accessing database data constantly which does not change often.

:::info[NOTE]
Even after implementing the cache, you should always check the hit ratio of your cache backend over a period of time, to ensure that your cache strategy is optimal.
:::

[Phalcon\Cache\Cache][cache-cache] components rely on `Phalcon\Storage` components. `Phalcon\Storage` is split into two categories: Serializers and Adapters.

## Cache

In order to instantiate a new [Phalcon\Cache\Cache][cache-cache] component, you will need to pass a `Phalcon\Cache\Adapter\*` class in it or one that implements the [Phalcon\Cache\Adapter\AdapterInterface][cache-adapter-adapterinterface]. For a detailed explanation of adapters and serializers, see below.

```php
<?php

use Phalcon\Cache\Cache;
use Phalcon\Cache\AdapterFactory;
use Phalcon\Storage\SerializerFactory;

$serializerFactory = new SerializerFactory();
$adapterFactory    = new AdapterFactory($serializerFactory);

$options = [
'defaultSerializer' => 'Json',
'lifetime'          => 7200
];

$adapter = $adapterFactory->newInstance('apcu', $options);

$cache = new Cache($adapter);
```

### Operations

The cache component implements methods that are in line with [PSR-16][psr-16] but does not implement `Psr\SimpleCache\CacheInterface` directly. The [phalcon/bridge-psr16][bridge-psr16] package bridges the two standards in both directions: a Phalcon cache can be consumed as a PSR-16 cache, and any PSR-16 cache can be used as a Phalcon cache back-end. See the [PSR-16](#psr-16) section below for installation and usage.

Each Cache component contains a supplied Cache adapter which in turn is responsible for all operations.

:::info[NOTE]
Cache keys are validated on every operation. A key must be a non-empty string containing only the characters `A-Z`, `a-z`, `0-9`, `-`, `_`, and `.`. An empty key, or one containing any other character, throws `Phalcon\Cache\Exception\InvalidArgumentException` before the operation runs. The same validation applies to every key in the `*Multiple` operations.
:::

### `get` - `getMultiple`

To get data from the cache you need to call the `get()` method with a key and a default value. If the key exists, or it has not expired, the data stored in it will be returned. Alternatively the passed `defaultValue` will be returned (default `null`).

```php
$value = $cache->get('my-key');

$value = $cache->get('my-key', 'default');
```

If you wish to retrieve more than one key with one call, you can call `getMultiple()`, passing an array with the keys needed. The method will return an array of `key` => `value` pairs. Cache keys that do not exist or have expired will have `defaultValue` as a value (default `null`).

```php
$value = $cache->getMultiple(['my-key1', 'my-key2']);

$value = $cache->getMultiple(['my-key1', 'my-key2'], 'default');
```

:::info[NOTE]
With the Redis adapter, `getMultiple()` uses a single `mget` call to retrieve every key at once, which is more efficient than one round trip per key. Each key is validated first, `Traversable` inputs are accepted, and a corrupt stored entry returns the default value, so the Redis path behaves like the per-key path used by the other adapters.
:::

### `has`

To check whether a key exists in the cache (or it has not expired) you can call the `has()` method. The method will return `true` if the key exists, or `false` otherwise.

```php
$exists = $cache->has('my-key');
```

### `set` - `setMultiple`

To save the data in the cache, you will need to use the `set()` method. The method accepts the key we wish to store the data under and the value of the item to store. The data needs to be of a type that supports serialization i.e. PHP type or an object that implements serialization. The last ( optional) parameter is the TTL (time to live) value for this item. This option might not always be available if the underlying adapter does not support it. The method will return `true` if the key exists, or `false` otherwise. If even one key is not successfully stored, the method will return `false`.

```php
$result = $cache->set('my-key', $data);
```

If you wish to store more than one element with one call, you can call `setMultiple()`, passing an array of key => value pairs for the multiple-set operation. As with `set` the last (optional) parameter is the TTL (time to live). The method will return `true` if the key exists, or `false` otherwise.

```php
$value = $cache->setMultiple(
[
    'my-key1' => $data1, 
    'my-key2' => $data2,
],
9600
);
```

:::info[NOTE]
Every key is validated before any value is written. If one of the keys is not a legal value, the operation throws `Phalcon\Cache\Exception\InvalidArgumentException` without storing any of the pairs.
:::

### `delete` - `deleteMultiple` - `clear`

To delete an item from the cache you need to call the `delete()` method with a key. The method returns `true` on success and `false` on failure.

```php
$result = $cache->delete('my-key');
```

If you wish to delete more than one key with one call, you can call `deleteMultiple()`, passing an array with the keys needed. The method returns `true` if all keys were successfully deleted, or `false` if any key did not exist or could not be deleted. The keys are validated before deletion - if a key contains invalid characters, a `Phalcon\Cache\Exception\InvalidArgumentException` will be thrown.

```php
$result = $cache->deleteMultiple(['my-key1', 'my-key2']);
```

If you wish to clear all the keys, you can call the `clear()` method. The method returns `true` on success and `false` on failure.

## Factory

### `newInstance`

We can create a [Phalcon\Cache\Cache][cache-cache] class using the `new` keyword. However, Phalcon offers the [Phalcon\Cache\CacheFactory][cache-cachefactory] class, so that developers can instantiate cache objects. The factory accepts a [Phalcon\Cache\AdapterFactory][cache-adapterfactory] object (which in turn requires a `Phalcon\Storage\SerializerFactory` object) and can instantiate the necessary Cache class with the selected adapter and options. The factory always returns a new instance of [Phalcon\Cache\Cache][cache-cache].

The example below shows how you can create a cache object using the `Apcu` adapter and `Json` serializer:

```php
<?php

use Phalcon\Cache\CacheFactory;
use Phalcon\Cache\AdapterFactory;
use Phalcon\Storage\SerializerFactory;

$options = [
'defaultSerializer' => 'Json',
'lifetime'          => 7200,
];

$serializerFactory = new SerializerFactory();
$adapterFactory    = new AdapterFactory(
$serializerFactory,
$options
);

$cacheFactory = new CacheFactory($adapterFactory);

$cache = $cacheFactory->newInstance('apcu');
```

### `load`

The Cache Factory also offers the `load` method, which accepts a configuration object. This object can be an array or a [Phalcon\Config\Config][config] object, with directives that are used to set up the cache. The object requires the `adapter` element, as well as the `options` element with the necessary directives.

```php
<?php

use Phalcon\Cache\CacheFactory;
use Phalcon\Cache\AdapterFactory;
use Phalcon\Storage\SerializerFactory;

$options = [
'defaultSerializer' => 'Json',
'lifetime'          => 7200,
];

$serializerFactory = new SerializerFactory();
$adapterFactory    = new AdapterFactory(
$serializerFactory,
$options
);

$cacheFactory = new CacheFactory($adapterFactory);

$cacheOptions = [
'adapter' => 'apcu',
'options' => [
    'prefix' => 'my-prefix',
],
];

$cache = $cacheFactory->load($cacheOptions);
```

## Serializers

The `Phalcon\Storage\Serializer` namespace offers classes that implement the [Serializable][serializable] interface and thus expose the `serialize` and `unserialize` methods. The purpose of these classes is to transform the data before saving it to the storage and after retrieving it from the storage.

:::info[NOTE]
The default serializer for all adapters is `Phalcon\Storage\Serializer\Php` which uses PHP's `serialize` and `unserialize` methods. These methods can suit most applications. However, the developer might want to use something more efficient such as [igbinary][igbinary] which is faster and achieves better compression.
:::

The cache adapter can be configured to use a different serializer. The available serializers are:

### `Base64`

This serializer uses the `base64_encode` and `base64_decode` methods to serialize data. The input must be of type `string`, therefore this serializer has obvious limitations

### `Igbinary`

The `igbinary` serializes relies on the `igbinary_serialize` and `igbinary_unserialize` methods. Those methods are exposed via the [igbinary][igbinary] PHP extension, which has to be installed and loaded on the target system.

### `Json`

The `JSON` serializer uses `json_encode` and `json_decode`. The target system must have JSON support available for PHP.

### `MemcachedIgbinary`

This serializer can be used when using `Memcached`. It corresponds to the built-in Igbinary serializer that `Memcached` has.

### `MemcachedJson`

This serializer can be used when using `Memcached`. It corresponds to the built-in JSON serializer that `Memcached` has.

### `MemcachedPhp`

This serializer can be used when using `Memcached`. It corresponds to the built-in PHP serializer that `Memcached` has.

### `Msgpack`

Similar to `igbinary` the `msgpack` serializer uses `msgpack_pack` and `msgpack_unpack` for serializing and unserializing data. This, along with `igbinary` is one of the fastest and most efficient serializers. However, it requires that the [msgpack][msgpack] PHP extension is loaded on the target system.

### `None`

This serializer does not transform the data at all. Both its `serialize` and `unserialize` get and set the data without altering it.

### `Php`

This is the default serializer. It uses PHP's `serialize` and `unserialize` methods for data transformations.

### `RedisIgbinary`

This serializer can be used when using `Redis`. It corresponds to the built-in Igbinary serializer that `Redis` has.

### `RedisJson`

This serializer can be used when using `Redis`. It corresponds to the built-in JSON serializer that `Redis` has.

### `RedisMsgpack`

This serializer can be used when using `Redis`. It corresponds to the built-in Msgpack serializer that `Redis` has.

### `RedisNone`

This serializer can be used when using `Redis`. It corresponds to the built-in None serializer that `Redis` has.

### `RedisPhp`

This serializer can be used when using `Redis`. It corresponds to the built-in PHP serializer that `Redis` has.

### Custom

Phalcon also offers the [Phalcon\Storage\Serializer\SerializerInterface][storage-serializer-serializerinterface] which can be implemented in a custom class. The class can offer the serialization you require.

```php
<?php

namespace MyApp\Storage\Serializer;

use Phalcon\Storage\Serializer\SerializerInterface;

class Garble implements SerializerInterface
{
/**
 * Data storage
 * 
 * @var string
 */
private $data = '';

/**
 * Return the stored data
 * 
 * @return string
 */
public function getData(): string
{
    return $this->data;
}       

/**
 * Serializes data
 */
public function serialize(): string
{
    return rot13($this->data);
}

/**
 * Set the data
 * 
 * @var Garble
 *
 * @return Garble
 */
public function setData($data): Garble
{
    $this->data = (string) $data;

    return $this;
}       

/**
 * Unserializes data
 */
public function unserialize($data): void
{
    $this->data = str_rot13($data);
}
}
```

Using it:

```php
<?php

namespace MyApp;

use MyApp\Storage\Serializer\Garble;

$data = 'I came, I saw, I conquered.';
$garble = new Garble();

$garble
->setData($data)
->serialize()  
;

echo $garble->getData(); // "V pnzr, V fnj, V pbadhrerq."

$encrypted = 'V pnzr, V fnj, V pbadhrerq.';

$garble->unserialize($encrypted);

echo $garble->getData(); // "I came, I saw, I conquered."
``` 

## Serializer Factory

Although all serializer classes can be instantiated using the `new` keyword, Phalcon offers the [Phalcon\Storage\SerializerFactory][storage-serializerfactory] class, so that developers can instantiate serializer classes. All the above serializers are registered in the factory and lazy loaded when called. The factory also allows you to register additional (custom) serializer classes. The only thing to consider is choosing the name of the serializer in comparison to the existing ones. If you define the same name, you will overwrite the built-in one. The objects are cached in the factory so if you call the `newInstance()` method with the same parameters during the same request, you will get the same object back.

The example below shows how you can create a `Json` serializer either using the `new` keyword or the factory:

```php
<?php

use Phalcon\Storage\Serializer\Json; 
use Phalcon\Storage\SerializerFactory;

$jsonSerializer = new Json();

$factory        = new SerializerFactory();
$jsonSerializer = $factory->newInstance('json');
```

The parameters you can use for the factory are:

| **Name**             | **Class**                                                                             |
|----------------------|---------------------------------------------------------------------------------------|
| `base64`             | [Phalcon\Storage\Serializer\Base64][storage-serializer-base64]                        |
| `igbinary`           | [Phalcon\Storage\Serializer\Igbinary][storage-serializer-igbinary]                    |
| `json`               | [Phalcon\Storage\Serializer\Json][storage-serializer-json]                            |
| `memcached_igbinary` | [Phalcon\Storage\Serializer\MemcachedIgbinary][storage-serializer-memcached-igbinary] |
| `memcached_json`     | [Phalcon\Storage\Serializer\MemcachedJson][storage-serializer-memcached-json]         |
| `memcached_php`      | [Phalcon\Storage\Serializer\MemcachedPhp][storage-serializer-memcached-php]           |
| `msgpack`            | [Phalcon\Storage\Serializer\Msgpack][storage-serializer-msgpack]                      |
| `none`               | [Phalcon\Storage\Serializer\None][storage-serializer-none]                            |
| `php`                | [Phalcon\Storage\Serializer\Php][storage-serializer-php]                              |
| `redis_igbinary`     | [Phalcon\Storage\Serializer\RedisIgbinary][storage-serializer-redis-igbinary]         |
| `redis_json`         | [Phalcon\Storage\Serializer\RedisJson][storage-serializer-redis-json]                 |
| `redis_msgpack`      | [Phalcon\Storage\Serializer\RedisMsgpack][storage-serializer-redis-msgpack]           |
| `redis_none`         | [Phalcon\Storage\Serializer\RedisNone][storage-serializer-redis-none]                 |
| `redis_php`          | [Phalcon\Storage\Serializer\RedisPhp][storage-serializer-redis-php]                   |

## Adapters

The `Phalcon\Cache\Adapter` namespace offers classes that implement the [Phalcon\Cache\Adapter\AdapterInterface][cache-adapter-adapterinterface] interface. It exposes common methods that are used to perform operations on the storage adapter or cache backend. These adapters act as wrappers to respective backend code.

The available methods are:

| Method           | Description                                                                |
|------------------|----------------------------------------------------------------------------|
| `clear`          | Flushes/clears the cache                                                   |
| `decrement`      | Decrements a stored number                                                 |
| `delete`         | Deletes data from the adapter                                              |
| `deleteMultiple` | Deletes multiple keys from the adapter in a single operation               |
| `get`            | Reads data from the adapter                                                |
| `getAdapter`     | Returns the already connected adapter or connects to the backend server(s) |
| `getKeys`        | Returns all the keys stored (optional filter parameter)                    |
| `getPrefix`      | Returns the prefix for the keys                                            |
| `has`            | Checks if an element exists in the cache                                   |
| `increment`      | Increments a stored number                                                 |
| `set`            | Stores data in the adapter                                                 |
| `setForever`     | Stores data in the adapter without an expiration                           |

:::info[NOTE]
The `getAdapter()` method returns the connected adapter. This offers more flexibility to the developer since it can be used to execute additional methods that each adapter offers. For instance, for the `Redis` adapter you can use the `getAdapter()` to obtain the connected object and call `zAdd`, `zRange`, and other methods not exposed by the Phalcon adapter.
:::

:::info[NOTE]
Keys returned by `getKeys()` carry the adapter prefix. The adapters also accept keys that already carry the prefix: `get()`, `has()`, `delete()`, `deleteMultiple()`, `set()`, `setForever()`, `increment()` and `decrement()` strip a leading prefix from the supplied key before applying their own, so the output of `getKeys()` can be passed back to these methods unchanged.
:::

:::warning[NOTE]
A consequence of the stripping is that a key whose name happens to start with the prefix text addresses the same record as the bare key: with prefix `data-`, `set('data-users', ...)` and `set('users', ...)` write to the same stored entry. If your keys are externally generated identifiers, or can legitimately begin with the prefix text, disable the behavior with the `stripPrefix` option (default `true`) when constructing the adapter.
:::

:::info[NOTE]
The adapters differ in counter atomicity and in how `getKeys()` is implemented - for example `Redis` enumerates keys with a non-blocking `SCAN`, while `Stream` walks the directory tree. See the [adapter capability matrix](/5.19/storage/#capability-matrix) in the Storage documentation for the per-adapter details.
:::

To construct one of these objects, you will need to pass a [Phalcon\Storage\SerializerFactory][storage-serializerfactory] object in the constructor and optionally some parameters required for the adapter of your choice. The list of options is outlined below.

The available adapters are:

### `Apcu`

This adapter uses `Apcu` to store the data. In order to use this adapter, you will need to have [apcu][apcu] enabled in your target system. This class does not use an actual _adapter_, since the `apcu` functionality is exposed using the `apcu_*` PHP functions.

| Option              | Default    |
|---------------------|------------|
| `defaultSerializer` | `Php`      |
| `lifetime`          | `3600`     |
| `serializer`        | `null`     |
| `prefix`            | `ph-apcu-` |
| `stripPrefix`       | `true`     |

The following example demonstrates how to create a new `Apcu` cache adapter, which will use the [Phalcon\Storage\Serializer\Json][storage-serializer-json] serializer and have a default lifetime of 7200.

```php
<?php

use Phalcon\Cache\Adapter\Apcu;
use Phalcon\Storage\SerializerFactory;

$serializerFactory = new SerializerFactory();

$options = [
'defaultSerializer' => 'Json',
'lifetime'          => 7200,
];

$adapter = new Apcu($serializerFactory, $options);
```

The above example used a [Phalcon\Storage\SerializerFactory][storage-serializerfactory] object and the `defaultSerializer` option to tell the adapter to instantiate the relevant serializer.

### `Libmemcached`

This adapter utilizes PHP's [memcached][memcached] extension to connect to Memcached servers. The adapter used is an instance of the `Memcached` class, created after the first event that requires the connection to be active.

| Option                                          | Default                               |
|-------------------------------------------------|---------------------------------------|
| `defaultSerializer`                             | `Php`                                 |
| `lifetime`                                      | `3600`                                |
| `serializer`                                    | `null`                                |
| `prefix`                                        | `ph-memc-`                            |
| `stripPrefix`                                   | `true`                                |
| `servers[0]['host']`                            | `127.0.0.1`                           |
| `servers[0]['port']`                            | `11211`                               |
| `servers[0]['weight']`                          | `1`                                   |
| `persistentId`                                  | `ph-mcid-`                            |
| `saslAuthData['user']`                          |                                       |
| `saslAuthData['pass']`                          |                                       |
| `client[\Memcached::OPT_CONNECT_TIMEOUT]`       | `10`                                  |
| `client[\Memcached::OPT_DISTRIBUTION]`          | `\Memcached::DISTRIBUTION_CONSISTENT` |
| `client[\Memcached::OPT_SERVER_FAILURE_LIMIT]`  | `2`                                   |
| `client[\Memcached::OPT_REMOVE_FAILED_SERVERS]` | `true`                                |
| `client[\Memcached::OPT_RETRY_TIMEOUT]`         | `1`                                   |

You can specify more than one server in the options array passed in the constructor. If `SASL` data is defined, the adapter will try to authenticate using the passed data. If there is an error in the options or the class cannot add one or more servers in the pool, a `Phalcon\Storage\Exception` will be thrown.

The following example demonstrates how to create a new `Libmemcached` cache adapter, which will use the [Phalcon\Storage\Serializer\Json][storage-serializer-json] serializer and have a default lifetime of 7200. It will use the `10.4.13.100` as the first server with weight `1` connecting to port `11211` and `10.4.13.110` as the second server with weight `5` again connecting to port `11211`.

```php
<?php

use Phalcon\Cache\Adapter\Libmemcached;
use Phalcon\Storage\SerializerFactory;

$serializerFactory = new SerializerFactory();

$options = [
'defaultSerializer' => 'Json',
'lifetime'          => 7200,
'servers'           => [
    0 => [
        'host'   => '10.4.13.100',
        'port'   => 11211,
        'weight' => 1,
    ],
    1 => [
        'host'   => '10.4.13.110',
        'port'   => 11211,
        'weight' => 5,
    ],
],
];

$adapter = new Libmemcached($serializerFactory, $options);
```

The above example used a [Phalcon\Storage\SerializerFactory][storage-serializerfactory] object and the `defaultSerializer` option to tell the adapter to instantiate the relevant serializer.

**Serializers**: The `Memcached` class which is the adapter that the [Phalcon\Cache\Adapter\Libmemcached][cache-adapter-libmemcached] uses, offers support for serializing out of the box. The built-in serializers are:

* `\Memcached::SERIALIZER_PHP`
* `\Memcached::SERIALIZER_JSON`
* `\Memcached::SERIALIZER_IGBINARY`

The [igbinary][igbinary] built-in serializer is only available if `igbinary` is present in the target system and [Memcached][memcached] extension is compiled with it. To enable these serializers, you can use the [Phalcon\Storage\Serializer\MemcachedIgbinary][storage-serializer-memcached-igbinary], [Phalcon\Storage\Serializer\MemcachedJson][storage-serializer-memcached-json] or [Phalcon\Storage\Serializer\MemcachedPhp][storage-serializer-memcached-php]

### `Memory`

This adapter uses the computer's memory to store the data. As all data is stored in memory, there is no persistence, meaning that once the request is completed, the data is lost. This adapter can be used for testing or temporary storage during a particular request. The options available for the constructor are:

| Option              | Default    |
|---------------------|------------|
| `defaultSerializer` | `Php`      |
| `lifetime`          | `3600`     |
| `serializer`        | `null`     |
| `prefix`            | `ph-memo-` |
| `stripPrefix`       | `true`     |

The following example demonstrates how to create a new `Memory` cache adapter, which will use the [Phalcon\Storage\Serializer\Json][storage-serializer-json] serializer and have a default lifetime of 7200.

```php
<?php

use Phalcon\Cache\Adapter\Memory;
use Phalcon\Storage\SerializerFactory;

$serializerFactory = new SerializerFactory();

$options = [
'defaultSerializer' => 'Json',
'lifetime'          => 7200,
];

$adapter = new Memory($serializerFactory, $options);
```

The above example used a [Phalcon\Storage\SerializerFactory][storage-serializerfactory] object and the `defaultSerializer` option to tell the adapter to instantiate the relevant serializer.

### `Redis`

This adapter utilizes PHP's [redis][redis] extension to connect to a Redis server. The adapter used is an instance of the `Redis` class, created after the first event that requires the connection to be active.

| Option              | Default     |
|---------------------|-------------|
| `defaultSerializer` | `Php`       |
| `lifetime`          | `3600`      |
| `serializer`        | `null`      |
| `prefix`            | `ph-reds-`  |
| `stripPrefix`       | `true`      |
| `host`              | `127.0.0.1` |
| `port`              | `6379`      |
| `index`             | `1`         |
| `persistent`        | `false`     |
| `auth`              |             |
| `socket`            |             |

If `auth` data is defined, the adapter will try to authenticate using the passed data. If there is an error in the options, or the server cannot connect or authenticate, a `Phalcon\Storage\Exception` will be thrown.

The following example demonstrates how to create a new `Redis` cache adapter, which will use the [Phalcon\Storage\Serializer\Json][storage-serializer-json] serializer and have a default lifetime of 7200. It will use the `10.4.13.100` as the host, connect to port `6379`, and select the index `1`.

```php
<?php

use Phalcon\Cache\Adapter\Redis;
use Phalcon\Storage\SerializerFactory;

$serializerFactory = new SerializerFactory();

$options = [
'defaultSerializer' => 'Json',
'lifetime'          => 7200,
'host'              => '10.4.13.100',
'port'              => 6379,
'index'             => 1,
];

$adapter = new Redis($serializerFactory, $options);
```

The above example used a [Phalcon\Storage\SerializerFactory][storage-serializerfactory] object and the `defaultSerializer` option to tell the adapter to instantiate the relevant serializer.

**Serializers**: The `Redis` class which is the adapter that the [Phalcon\Cache\Adapter\Redis][cache-adapter-redis] uses, offers support for serializing out of the box. The built-in serializers are:

* `\Redis::SERIALIZER_NONE`
* `\Redis::SERIALIZER_PHP`
* `\Redis::SERIALIZER_IGBINARY`
* `\Redis::SERIALIZER_MSGPACK`

The [igbinary][igbinary] and built-in serializer are only available if `igbinary` is present in the target system and [Redis][redis] extension is compiled with it. The same applies to [msgpack][msgpack] built-in serializer. It is only available if `msgpack` is present in the target system and the [Redis][redis] extension is compiled with it. To enable these serializers, you can use the [Phalcon\Storage\Serializer\RedisIgbinary][storage-serializer-redis-igbinary], [Phalcon\Storage\Serializer\RedisJson][storage-serializer-redis-json], [Phalcon\Storage\Serializer\RedisMsgpack][storage-serializer-redis-msgpack], [Phalcon\Storage\Serializer\RedisNone][storage-serializer-redis-none] or [Phalcon\Storage\Serializer\RedisPhp][storage-serializer-redis-php].

**NOTE** `increment` - `decrement`

At this point in time, there is an issue with `Redis`, where the internal `Redis` serializer does not skip scalar values because it can only store strings. As a result, if you use `increment` after a `set` for a number, will not return a number:

The way to store numbers and use the `increment` (or `decrement`) is to either remove the internal serializer for `Redis`

```php
$cache->getAdapter()->setOption(\Redis::OPT_SERIALIZER, \Redis::SERIALIZER_NONE);
```

or you could use `increment` instead of using `set` at the first setting of the value to the key:

```php
$cache->delete('my-key');
$cache->increment('my-key', 2);
echo $cache->get('my-key');      // 2
$cache->increment('my-key', 3);
echo $cache->get('my-key');      // 3
```

### `Stream`

This adapter is the simplest to set up since it uses the target system's file system (it only requires a cache path that is writeable). It is one of the slowest cache adapters since the data has to be written to the file system. Each file created corresponds to a key stored. The file contains additional metadata to calculate the lifetime of the cache element, resulting in additional reads and writes to the file system.

| Option              | Default   |
|---------------------|-----------|
| `defaultSerializer` | `Php`     |
| `lifetime`          | `3600`    |
| `serializer`        | `null`    |
| `prefix`            | `phstrm-` |
| `stripPrefix`       | `true`    |
| `storageDir`        |           |

If the `storageDir` is not defined a `Phalcon\Storage\Exception` will be thrown.

:::info[NOTE]
The adapter utilizes logic to store files in separate subdirectories based on the name of the key passed, thus avoiding the `too many files in one folder` limit present in Windows or Linux-based systems.
:::

The following example demonstrates how to create a new `Stream` cache adapter, which will use the [Phalcon\Storage\Serializer\Json][storage-serializer-json] serializer and have a default lifetime of 7200. It will store the cached data in `/data/storage/cache`.

```php
<?php

use Phalcon\Cache\Adapter\Stream;
use Phalcon\Storage\SerializerFactory;

$serializerFactory = new SerializerFactory();

$options = [
'defaultSerializer' => 'Json',
'lifetime'          => 7200,
'storageDir'        => '/data/storage/cache',
];

$adapter = new Stream($serializerFactory, $options);
```

The above example used a [Phalcon\Storage\SerializerFactory][storage-serializerfactory] object and the `defaultSerializer` option to tell the adapter to instantiate the relevant serializer.

### Custom

Phalcon also offers the [Phalcon\Cache\Adapter\AdapterInterface][cache-adapter-adapterinterface] which can be implemented in a custom class. The class can offer the cache adapter functionality you require.

```php
<?php

namespace MyApp\Cache\Adapter;

use Phalcon\Cache\Adapter\AdapterInterface;

class Custom implements AdapterInterface
{
/**
 * Flushes/clears the cache
 */
public function clear(): bool
{
    // Custom implementation
}

/**
 * Decrements a stored number
 */
public function decrement(string $key, int $value = 1)
{
    // Custom implementation
}

/**
 * Deletes data from the adapter
 */
public function delete(string $key): bool
{
    // Custom implementation
}

/**
 * Deletes multiple keys from the adapter
 */
public function deleteMultiple(array $keys): bool
{
    // Custom implementation
}

/**
 * Reads data from the adapter
 */
public function get(string $key)
{
    // Custom implementation
}

/**
 * Returns the already connected adapter or connects to the backend server(s)
 */
public function getAdapter()
{
    // Custom implementation
}

/**
 * Returns all the keys stored. If a filter has been passed the 
 * keys that match the filter will be returned
 */
public function getKeys(string $prefix = ""): array
{
    // Custom implementation
}

/**
 * Returns the prefix for the keys
 */
public function getPrefix(): string
{
    // Custom implementation
}

/**
 * Checks if an element exists in the cache
 */
public function has(string $key): bool
{
    // Custom implementation
}

/**
 * Increments a stored number
 */
public function increment(string $key, int $value = 1)
{
    // Custom implementation
}

/**
 * Stores data in the adapter
 */
public function set(string $key, $value, $ttl = null): bool
{
    // Custom implementation
}
}
```

Using it:

```php
<?php

namespace MyApp;

use MyApp\Cache\Adapter\Custom;

$custom = new Custom();

$custom->set('my-key', $data);
``` 

## Adapter Factory

Although all adapter classes can be instantiated using the `new` keyword, Phalcon offers the [Phalcon\Cache\AdapterFactory][cache-adapterfactory] class, so that you can instantiate cache adapter classes. All the above adapters are registered in the factory and lazy loaded when called. The factory also allows you to register additional (custom) adapter classes. The only thing to consider is choosing the name of the adapter in comparison to the existing ones. If you define the same name, you will overwrite the built-in one. The objects are cached in the factory so if you call the `newInstance()` method with the same parameters during the same request, you will get the same object back.

The example below shows how you can create an `Apcu` cache adapter with the `new` keyword or the factory:

```php
<?php

use Phalcon\Cache\Adapter\Apcu;
use Phalcon\Storage\Serializer\Json;

$jsonSerializer = new Json();

$options = [
'defaultSerializer' => 'Json',
'lifetime'          => 7200,
'serializer'        => $jsonSerializer,
];

$adapter = new Apcu(null, $options);
```

```php
<?php

use Phalcon\Cache\AdapterFactory;
use Phalcon\Storage\SerializerFactory;

$serializerFactory = new SerializerFactory();
$adapterFactory    = new AdapterFactory($serializerFactory);

$options = [
'defaultSerializer' => 'Json',
'lifetime'          => 7200,
];

$adapter = $adapterFactory->newInstance('apcu', $options);
```

The parameters you can use for the factory are:

| Name           | Adapter                                                          |
|----------------|------------------------------------------------------------------|
| `apcu`         | [Phalcon\Cache\Adapter\Apcu][cache-adapter-apcu]                 |
| `libmemcached` | [Phalcon\Cache\Adapter\Libmemcached][cache-adapter-libmemcached] |
| `memory`       | [Phalcon\Cache\Adapter\Memory][cache-adapter-memory]             |
| `redis`        | [Phalcon\Cache\Adapter\Redis][cache-adapter-redis]               |
| `stream`       | [Phalcon\Cache\Adapter\Stream][cache-adapter-stream]             |

## Events

The [Phalcon\Cache\AbstractCache][cache-abstract-cache] object implements the [Phalcon\Events\EventsAware][events-eventsawareinterface] interfaces. As a result `getEventsManager()` and `setEventsManager()` are available for you to use.

| Event                  | Description                                     | Emitted by | Can stop operation |
|------------------------|-------------------------------------------------|------------|:------------------:|
| `beforeSet`            | Fires before the value is set                   | Both       |         No         |
| `afterSet`             | Fires after the value has been set              | Both       |         No         |
| `beforeGet`            | Fires before the value is requested             | Both       |         No         |
| `afterGet`             | Fires after the value has been requested        | Both       |         No         |
| `beforeHas`            | Fires before the value is requested             | Both       |         No         |
| `afterHas`             | Fires after the value has been requested        | Both       |         No         |
| `beforeDelete`         | Fires before the value is deleted               | Both       |         No         |
| `afterDelete`          | Fires after the value has been deleted          | Both       |         No         |
| `beforeDeleteMultiple` | Fires before multiple values are deleted        | Both       |         No         |
| `afterDeleteMultiple`  | Fires after multiple values have been deleted   | Both       |         No         |
| `beforeGetMultiple`    | Fires before multiple values are requested      | Facade     |         No         |
| `afterGetMultiple`     | Fires after multiple values have been requested | Facade     |         No         |
| `beforeSetMultiple`    | Fires before multiple values are set            | Facade     |         No         |
| `afterSetMultiple`     | Fires after multiple values have been set       | Facade     |         No         |
| `beforeIncrement`      | Fires before the value has been incremented     | Adapter    |         No         |
| `afterIncrement`       | Fires after the value has been incremented      | Adapter    |         No         |
| `beforeDecrement`      | Fires before the value has been decremented     | Adapter    |         No         |
| `afterDecrement`       | Fires after the value has been decremented      | Adapter    |         No         |

The `Emitted by` column refers to the two layers described below: the cache facade ([Phalcon\Cache\Cache][cache-cache]) and the underlying cache adapter (for instance [Phalcon\Cache\Adapter\Apcu][cache-adapter-apcu]).

### Event Layers

Cache operations can emit `cache:*` events from two layers. The cache facade ([Phalcon\Cache\AbstractCache][cache-abstract-cache]) fires `cache:before*` and `cache:after*` around each operation, and the underlying `Storage` adapter also fires `cache:*` events for the same operation. If you wire an events manager into both the cache object and its adapter, a single operation emits each event twice. Wire the manager into one layer only. The cache facade is the supported source for cache-level events.

The two layers do not emit an identical set of events:

* `cache:beforeGetMultiple`, `cache:afterGetMultiple`, `cache:beforeSetMultiple` and `cache:afterSetMultiple` are emitted by the facade only. The adapter offers no `getMultiple()` or `setMultiple()` method.
* `cache:beforeIncrement`, `cache:afterIncrement`, `cache:beforeDecrement` and `cache:afterDecrement` are emitted by the adapter only. The facade offers no `increment()` or `decrement()` method, so these events never reach an events manager wired into the facade alone. Listen for them on the adapter, which you can reach with `getAdapter()`.
* `cache:beforeDeleteMultiple` and `cache:afterDeleteMultiple` are emitted by both layers, since the facade delegates `deleteMultiple()` to the adapter method of the same name.

The `before*` events fire only after key validation passes, so an operation that throws on an invalid key does not emit its `before*` event.

## Contracts

The canonical interface for this component lives in the `Phalcon\Contracts\Cache` namespace, with the `Interface` suffix dropped. `Phalcon\Cache\CacheInterface` remains available: it now extends its contract and is deprecated. Existing implementations and type hints keep working unchanged; new code should target the contract.

| Deprecated interface           | Canonical contract              |
|---------------------------------|---------------------------------|
| `Phalcon\Cache\CacheInterface`  | `Phalcon\Contracts\Cache\Cache` |

`Phalcon\Contracts\Cache\Cache` declares the PSR-16-shaped cache surface (`get`, `set`, `has`, `delete`, `clear`, and the `*Multiple` variants). It does not extend `Psr\SimpleCache\CacheInterface`.

## Exceptions

Any exception thrown in the Cache component is of type [Phalcon\Cache\Exception\Exception][cache-exception-exception]. Invalid arguments - a cache key that is not a string or contains reserved characters, or a non-iterable set of keys passed to `getMultiple()` / `setMultiple()` / `deleteMultiple()` - raise [Phalcon\Cache\Exception\InvalidArgumentException][cache-exception-invalidargumentexception] instead. Both extend `\Exception`. You can use these exceptions to selectively catch failures from this component.

```php
<?php

use Phalcon\Cache\Exception\Exception;
use Phalcon\Mvc\Controller;

class IndexController extends Controller
{
public function index()
{
    try {
        $content = $this->cache->get('some-key');
    } catch (Exception $ex) {
        echo $ex->getMessage();
    }
}
}
```

## PSR-16

[Phalcon\Cache\Cache][cache-cache] implements methods that are in line with [PSR-16][psr-16] but does not implement `Psr\SimpleCache\CacheInterface` directly, and its exceptions are not PSR-16 typed. The [phalcon/bridge-psr16][bridge-psr16] package bridges the two standards in both directions.

- Requires PHP 8.1 or later
- Works with the Phalcon C extension or the `phalcon/phalcon` package
- Targets `psr/simple-cache` (PSR-16) version 3

Install the package with composer:

```sh
composer require phalcon/bridge-psr16
```

The package provides two classes, one for each direction, plus a `Psr\SimpleCache\InvalidArgumentException` so illegal-key failures can be caught through the PSR-16 marker.

### Phalcon Cache as a PSR-16 Cache

`Phalcon\Bridge\Psr16\Cache` is a `Psr\SimpleCache\CacheInterface` backed by a Phalcon cache adapter. Use it when a component requires a PSR-16 cache and the storage needs to go through Phalcon. Its constructor takes any [Phalcon\Cache\Adapter\AdapterInterface][cache-adapter-adapterinterface], such as one built with [Phalcon\Cache\AdapterFactory][cache-adapterfactory].

```php
<?php

use Phalcon\Bridge\Psr16\Cache;
use Phalcon\Cache\AdapterFactory;
use Phalcon\Storage\SerializerFactory;

$adapterFactory = new AdapterFactory(new SerializerFactory());
$adapter        = $adapterFactory->newInstance('memory');

$cache = new Cache($adapter);

// $cache is a Psr\SimpleCache\CacheInterface
$cache->set('user.42', ['name' => 'Phalcon'], 3600);
$data = $cache->get('user.42');
```

An illegal key raises `Phalcon\Bridge\Psr16\Exception\InvalidArgumentException`, which implements `Psr\SimpleCache\InvalidArgumentException`, so callers can catch the PSR-16 marker.

### PSR-16 Cache as a Phalcon Backend

`Phalcon\Bridge\Psr16\Adapter` is a Phalcon cache adapter that forwards every operation to a wrapped `Psr\SimpleCache\CacheInterface`. Use it when a PSR-16 cache already exists, such as Symfony Cache, and it needs to back a [Phalcon\Cache\Cache][cache-cache]. Serialization is left to the PSR-16 cache to avoid double-encoding.

```php
<?php

use Phalcon\Bridge\Psr16\Adapter;
use Phalcon\Cache\Cache;
use Phalcon\Storage\SerializerFactory;

// Any Psr\SimpleCache\CacheInterface, e.g. Symfony's Psr16Cache
$psr = new Symfony\Component\Cache\Psr16Cache(/* ... */);

$adapter = new Adapter(new SerializerFactory(), $psr);
$cache   = new Cache($adapter);

// Phalcon cache calls now flow into the PSR-16 cache
$cache->set('key', 'value');
```

PSR-16 has no atomic counters or key enumeration, so `increment()` / `decrement()` are emulated non-atomically and `getKeys()` returns an empty array.

[apcu]: https://www.php.net/manual/en/book.apcu.php
[cache-abstract-cache]: /5.19/api/phalcon_cache/#cacheabstractcache
[cache-adapter-adapterinterface]: /5.19/api/phalcon_cache/#cacheadapteradapterinterface
[cache-adapter-apcu]: /5.19/api/phalcon_cache/#cacheadapterapcu
[cache-adapter-libmemcached]: /5.19/api/phalcon_cache/#cacheadapterlibmemcached
[cache-adapter-memory]: /5.19/api/phalcon_cache/#cacheadaptermemory
[cache-adapter-redis]: /5.19/api/phalcon_cache/#cacheadapterredis
[cache-adapter-stream]: /5.19/api/phalcon_cache/#cacheadapterstream
[cache-adapterfactory]: /5.19/api/phalcon_cache/#cacheadapterfactory
[cache-cache]: /5.19/api/phalcon_cache/#cachecache
[cache-cachefactory]: /5.19/api/phalcon_cache/#cachecachefactory
[cache-exception-exception]: /5.19/api/phalcon_cache/#cacheexceptionexception
[cache-exception-invalidargumentexception]: /5.19/api/phalcon_cache/#cacheexceptioninvalidargumentexception
[config]: /5.19/config/
[events-eventsawareinterface]: /5.19/api/phalcon_events/#eventseventsawareinterface
[igbinary]: https://github.com/igbinary/igbinary7
[memcached]: https://www.php.net/manual/en/book.memcached.php
[msgpack]: https://msgpack.org/
[bridge-psr16]: https://github.com/phalcon/bridge-psr16
[psr-16]: https://www.php-fig.org/psr/psr-16/
[redis]: https://github.com/phpredis/phpredis
[serializable]: https://www.php.net/manual/en/class.serializable.php
[storage-adapter-abstractadapter]: /5.19/api/phalcon_storage/#storageadapterabstractadapter
[storage-adapter-adapterinterface]: /5.19/api/phalcon_storage/#storageadapteradapterinterface
[storage-adapter-apcu]: /5.19/api/phalcon_storage/#storageadapterapcu
[storage-adapter-libmemcached]: /5.19/api/phalcon_storage/#storageadapterlibmemcached
[storage-adapter-memory]: /5.19/api/phalcon_storage/#storageadaptermemory
[storage-adapter-redis]: /5.19/api/phalcon_storage/#storageadapterredis
[storage-adapter-stream]: /5.19/api/phalcon_storage/#storageadapterstream
[storage-adapterfactory]: /5.19/api/phalcon_storage/#storageadapterfactory
[storage-exception]: /5.19/api/phalcon_storage/#storageexception
[storage-serializer-abstractserializer]: /5.19/api/phalcon_storage/#storageserializerabstractserializer
[storage-serializer-base64]: /5.19/api/phalcon_storage/#storageserializerbase64
[storage-serializer-igbinary]: /5.19/api/phalcon_storage/#storageserializerigbinary
[storage-serializer-json]: /5.19/api/phalcon_storage/#storageserializerjson
[storage-serializer-memcached-igbinary]: /5.19/api/phalcon_storage/#storageserializermemcachedigbinary
[storage-serializer-memcached-json]: /5.19/api/phalcon_storage/#storageserializermemcachedjson
[storage-serializer-memcached-php]: /5.19/api/phalcon_storage/#storageserializermemcachedphp
[storage-serializer-msgpack]: /5.19/api/phalcon_storage/#storageserializermsgpack
[storage-serializer-none]: /5.19/api/phalcon_storage/#storageserializernone
[storage-serializer-php]: /5.19/api/phalcon_storage/#storageserializerphp
[storage-serializer-redis-igbinary]: /5.19/api/phalcon_storage/#storageserializerredisigbinary
[storage-serializer-redis-json]: /5.19/api/phalcon_storage/#storageserializerredisjson
[storage-serializer-redis-msgpack]: /5.19/api/phalcon_storage/#storageserializerredismsgpack
[storage-serializer-redis-none]: /5.19/api/phalcon_storage/#storageserializerredisnone
[storage-serializer-redis-php]: /5.19/api/phalcon_storage/#storageserializerredisphp
[storage-serializer-serializerinterface]: /5.19/api/phalcon_storage/#storageserializerserializerinterface
[storage-serializerfactory]: /5.19/api/phalcon_storage/#storageserializerfactory

Source: https://docs.phalcon.io/5.19/cache/index.mdx