Zend\Cache\Storage\Adapter¶
Overview¶
Storage adapters are wrappers for real storage resources such as memory and the filesystem, using the well known adapter pattern.
They come with tons of methods to read, write and modify stored items and to get information about stored items and the storage.
All adapters implement the interface Zend\Cache\Storage\StorageInterface and most extend Zend\Cache\Storage\Adapter\AbstractAdapter, which comes with basic logic.
Configuration is handled by either Zend\Cache\Storage\Adapter\AdapterOptions, or an adapter-specific options class if it exists. You may pass the options instance to the class at instantiation or via the setOptions() method, or alternately pass an associative array of options in either place (internally, these are then passed to an options class instance). Alternately, you can pass either the options instance or associative array to the Zend\Cache\StorageFactory::factory method.
Note
Many methods throw exceptions
Because many caching operations throw an exception on error, you need to catch them manually or you can use the plug-in Zend\Cache\Storage\Plugin\ExceptionHandler with throw_exceptions set to false to automatically catch them. You can also define an exception_callback to log exceptions.
Quick Start¶
Caching adapters can either be created from the provided Zend\Cache\StorageFactory factory, or by simply instantiating one of the Zend\Cache\Storage\Adapter\* classes.
To make life easier, the Zend\Cache\StorageFactory comes with a factory method to create an adapter and create/add all requested plugins at once.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 | use Zend\Cache\StorageFactory;
// Via factory:
$cache = StorageFactory::factory(array(
'adapter' => array(
'name' => 'apc',
'options' => array('ttl' => 3600),
),
'plugins' => array(
'exception_handler' => array('throw_exceptions' => false),
),
));
// Alternately:
$cache = StorageFactory::adapterFactory('apc', array('ttl' => 3600));
$plugin = StorageFactory::pluginFactory('exception_handler', array(
'throw_exceptions' => false,
));
$cache->addPlugin($plugin);
// Or manually:
$cache = new Zend\Cache\Storage\Adapter\Apc();
$cache->getOptions()->setTtl(3600);
$plugin = new Zend\Cache\Storage\Plugin\ExceptionHandler();
$plugin->getOptions()->setThrowExceptions(false);
$cache->addPlugin($plugin);
|
Basic Configuration Options¶
Basic configuration is handled by either Zend\Cache\Storage\Adapter\AdapterOptions, or an adapter-specific options class if it exists. You may pass the options instance to the class at instantiation or via the setOptions() method, or alternately pass an associative array of options in either place (internally, these are then passed to an options class instance). Alternately, you can pass either the options instance or associative array to the Zend\Cache\StorageFactory::factory method.
The following configuration options are defined by Zend\Cache\Storage\Adapter\AdapterOptions and are available for every supported adapter. Adapter-specific configuration options are described on adapter level below.
Option Data Type Default Value Description ttl integer 0 Time to live namespace string “zfcache” The “namespace” in which cache items will live key_pattern null``|``string null Pattern against which to validate cache keys readable boolean true Enable/Disable reading data from cache writable boolean true Enable/Disable writing data to cache
The StorageInterface¶
The Zend\Cache\Storage\StorageInterface is the basic interface implemented by all storage adapters.
- getItem(string $key, boolean & $success = null, mixed & $casToken = null)
Load an item with the given $key.
If item exists set parameter $success to true, set parameter $casToken and returns mixed value of item.
If item can’t load set parameter $success to false and returns null.
Return type: mixed
- getItems(array $keys)
Load all items given by $keys returning key-value pairs.
Return type: array
- hasItem(string $key)
Test if an item exists.
Return type: boolean
- hasItems(array $keys)
Test multiple items.
Return type: string[]
- getMetadata(string $key)
Get metadata of an item.
Return type: array|boolean
- getMetadatas(array $keys)
Get multiple metadata.
Return type: array
- setItem(string $key, mixed $value)
Store an item.
Return type: boolean
- setItems(array $keyValuePairs)
Store multiple items.
Return type: boolean
- addItem(string $key, mixed $value)
Add an item.
Return type: boolean
- addItems(array $keyValuePairs)
Add multiple items.
Return type: boolean
- replaceItem(string $key, mixed $value)
Replace an item.
Return type: boolean
- replaceItems(array $keyValuePairs)
Replace multiple items.
Return type: boolean
- checkAndSetItem(mixed $token, string $key, mixed $value)
Set item only if token matches. It uses the token received from getItem() to check if the item has changed before overwriting it.
Return type: boolean
- touchItem(string $key)
Reset lifetime of an item.
Return type: boolean
- touchItems(array $keys)
Reset lifetime of multiple items.
Return type: boolean
- removeItem(string $key)
Remove an item.
Return type: boolean
- removeItems(array $keys)
Remove multiple items.
Return type: boolean
- incrementItem(string $key, int $value)
Increment an item.
Return type: integer|boolean
- incrementItems(array $keyValuePairs)
Increment multiple items.
Return type: boolean
- decrementItem(string $key, int $value)
Decrement an item.
Return type: integer|boolean
- decrementItems(array $keyValuePairs)
Decrement multiple items.
Return type: boolean
- getCapabilities()
Capabilities of this storage.
Return type: Zend\Cache\Storage\Capabilities
The AvailableSpaceCapableInterface¶
The Zend\Cache\Storage\AvailableSpaceCapableInterface implements a method to make it possible getting the current available space of the storage.
- getAvailableSpace()
Get available space in bytes.
Return type: integer|float
The TotalSpaceCapableInterface¶
The Zend\Cache\Storage\TotalSpaceCapableInterface implements a method to make it possible getting the total space of the storage.
- getTotalSpace()
Get total space in bytes.
Return type: integer|float
The ClearByNamespaceInterface¶
The Zend\Cache\Storage\ClearByNamespaceInterface implements a method to clear all items of a given namespace.
- clearByNamespace(string $namespace)
Remove items of given namespace.
Return type: boolean
The ClearByPrefixInterface¶
The Zend\Cache\Storage\ClearByPrefixInterface implements a method to clear all items of a given prefix (within the current configured namespace).
- clearByPrefix(string $prefix)
Remove items matching given prefix.
Return type: boolean
The ClearExpiredInterface¶
The Zend\Cache\Storage\ClearExpiredInterface implements a method to clear all expired items (within the current configured namespace).
- clearExpired()
Remove expired items.
Return type: boolean
The FlushableInterface¶
The Zend\Cache\Storage\FlushableInterface implements a method to flush the complete storage.
- flush()
Flush the whole storage.
Return type: boolean
The IterableInterface¶
The Zend\Cache\Storage\IterableInterface implements a method to get an iterator to iterate over items of the storage. It extends IteratorAggregate so it’s possible to directly iterate over the storage using foreach.
- getIterator()
Get an Iterator.
Return type: Zend\Cache\Storage\IteratorInterface
The OptimizableInterface¶
The Zend\Cache\Storage\OptimizableInterface implements a method to run optimization processes on the storage.
- optimize()
Optimize the storage.
Return type: boolean
The TaggableInterface¶
The Zend\Cache\Storage\TaggableInterface implements methods to mark items with one or more tags and to clean items matching tags.
- setTags(string $key, string[] $tags)
Set tags to an item by given key. (An empty array will remove all tags)
Return type: boolean
- getTags(string $key)
Get tags of an item by given key.
Return type: string[]|false
- clearByTags(string[] $tags, boolean $disjunction = false)
Remove items matching given tags.
If $disjunction is true only one of the given tags must match else all given tags must match.
Return type: boolean
The Apc Adapter¶
The Zend\Cache\Storage\Adapter\Apc adapter stores cache items in shared memory through the required PHP extension APC (Alternative PHP Cache).
This adapter implements the following interfaces:
- Zend\Cache\Storage\StorageInterface
- Zend\Cache\Storage\AvailableSpaceCapableInterface
- Zend\Cache\Storage\ClearByNamespaceInterface
- Zend\Cache\Storage\ClearByPrefixInterface
- Zend\Cache\Storage\FlushableInterface
- Zend\Cache\Storage\IterableInterface
- Zend\Cache\Storage\TotalSpaceCapableInterface
Capability | Value |
---|---|
supportedDatatypes | null, boolean, integer, double, string, array (serialized), object (serialized) |
supportedMetadata | internal_key, atime, ctime, mtime, rtime, size, hits, ttl |
minTtl | 1 |
maxTtl | 0 |
staticTtl | true |
ttlPrecision | 1 |
useRequestTime | <ini value of apc.use_request_time> |
expiredRead | false |
maxKeyLength | 5182 |
namespaceIsPrefix | true |
namespaceSeparator | <Option value of namespace_separator> |
Name | Data Type | Default Value | Description |
---|---|---|---|
namespace_separator | string | ”:” | A separator for the namespace and prefix |
The Dba Adapter¶
The Zend\Cache\Storage\Adapter\Dba adapter stores cache items into dbm like databases using the required PHP extension dba.
This adapter implements the following interfaces:
- Zend\Cache\Storage\StorageInterface
- Zend\Cache\Storage\AvailableSpaceCapableInterface
- Zend\Cache\Storage\ClearByNamespaceInterface
- Zend\Cache\Storage\ClearByPrefixInterface
- Zend\Cache\Storage\FlushableInterface
- Zend\Cache\Storage\IterableInterface
- Zend\Cache\Storage\OptimizableInterface
- Zend\Cache\Storage\TotalSpaceCapableInterface
Capability | Value |
---|---|
supportedDatatypes | string, null => string, boolean => string, integer => string, double => string |
supportedMetadata | <none> |
minTtl | 0 |
maxKeyLength | 0 |
namespaceIsPrefix | true |
namespaceSeparator | <Option value of namespace_separator> |
Name | Data Type | Default Value | Description |
---|---|---|---|
namespace_separator | string | ”:” | A separator for the namespace and prefix |
pathname | string | “” | Pathname to the database file |
mode | string | “c” | The mode to open the database Please read dba_open for more information |
handler | string | “flatfile” | The name of the handler which shall be used for accessing the database. |
Note
This adapter doesn’t support automatically expire items
Because of this adapter doesn’t support automatically expire items it’s very important to clean outdated items by self.
The Filesystem Adapter¶
The Zend\Cache\Storage\Adapter\Filesystem adapter stores cache items into the filesystem.
This adapter implements the following interfaces:
- Zend\Cache\Storage\StorageInterface
- Zend\Cache\Storage\AvailableSpaceCapableInterface
- Zend\Cache\Storage\ClearByNamespaceInterface
- Zend\Cache\Storage\ClearByPrefixInterface
- Zend\Cache\Storage\ClearExpiredInterface
- Zend\Cache\Storage\FlushableInterface
- Zend\Cache\Storage\IterableInterface
- Zend\Cache\Storage\OptimizableInterface
- Zend\Cache\Storage\TaggableInterface
- Zend\Cache\Storage\TotalSpaceCapableInterface
Capability | Value |
---|---|
supportedDatatypes | string, null => string, boolean => string, integer => string, double => string |
supportedMetadata | mtime, filespec, atime, ctime |
minTtl | 1 |
maxTtl | 0 |
staticTtl | false |
ttlPrecision | 1 |
useRequestTime | false |
expiredRead | true |
maxKeyLength | 251 |
namespaceIsPrefix | true |
namespaceSeparator | <Option value of namespace_separator> |
Name | Data Type | Default Value | Description |
---|---|---|---|
namespace_separator | string | ”:” | A separator for the namespace and prefix |
cache_dir | string | “” | Directory to store cache files |
clear_stat_cache | boolean | true | Call clearstatcache() enabled? |
dir_level | integer | 1 | Defines how much sub-directories should be created |
dir_permission | integer false | 0700 | Set explicit permission on creating new directories |
file_locking | boolean | true | Lock files on writing |
file_permission | integer false | 0600 | Set explicit permission on creating new files |
key_pattern | string | /^[a-z0-9_\+\-]*$/Di | Validate key against pattern |
no_atime | boolean | true | Don’t get ‘fileatime’ as ‘atime’ on metadata |
no_ctime | boolean | true | Don’t get ‘filectime’ as ‘ctime’ on metadata |
umask | integer false | false | Use umask to set file and directory permissions |
The Memcached Adapter¶
The Zend\Cache\Storage\Adapter\Memcached adapter stores cache items over the memcached protocol. It’s using the required PHP extension memcached which is based on Libmemcached.
This adapter implements the following interfaces:
- Zend\Cache\Storage\StorageInterface
- Zend\Cache\Storage\AvailableSpaceCapableInterface
- Zend\Cache\Storage\FlushableInterface
- Zend\Cache\Storage\TotalSpaceCapableInterface
Capability | Value |
---|---|
supportedDatatypes | null, boolean, integer, double, string, array (serialized), object (serialized) |
supportedMetadata | <none> |
minTtl | 1 |
maxTtl | 0 |
staticTtl | true |
ttlPrecision | 1 |
useRequestTime | false |
expiredRead | false |
maxKeyLength | 255 |
namespaceIsPrefix | true |
namespaceSeparator | <none> |
Name | Data Type | Default Value | Description |
---|---|---|---|
servers | array | [] | List of servers in [] = array(string host, integer port) |
lib_options | array | [] | Associative array of Libmemcached options were the array key is the option name (without the prefix “OPT_”) or the constant value. The array value is the option value Please read this<http://php.net/manual/memcached.setoption.php> for more information |
The Memory Adapter¶
The Zend\Cache\Storage\Adapter\Memory adapter stores cache items into the PHP process using an array.
This adapter implements the following interfaces:
- Zend\Cache\Storage\StorageInterface
- Zend\Cache\Storage\AvailableSpaceCapableInterface
- Zend\Cache\Storage\ClearByPrefixInterface
- Zend\Cache\Storage\ClearExpiredInterface
- Zend\Cache\Storage\FlushableInterface
- Zend\Cache\Storage\IterableInterface
- Zend\Cache\Storage\TaggableInterface
- Zend\Cache\Storage\TotalSpaceCapableInterface
Capability | Value |
---|---|
supportedDatatypes | string, null, boolean, integer, double, array, object, resource |
supportedMetadata | mtime |
minTtl | 1 |
maxTtl | <Value of PHP_INT_MAX> |
staticTtl | false |
ttlPrecision | 0.05 |
useRequestTime | false |
expiredRead | true |
maxKeyLength | 0 |
namespaceIsPrefix | false |
Name | Data Type | Default Value | Description |
---|---|---|---|
memory_limit | string integer | <50% of ini value memory_limit> | Limit of how much memory can PHP allocate to allow store items into this adapter
|
Note
All stored items will be lost after terminating the script.
The WinCache Adapter¶
The Zend\Cache\Storage\Adapter\WinCache adapter stores cache items into shared memory through the required PHP extension WinCache.
This adapter implements the following interfaces:
- Zend\Cache\Storage\StorageInterface
- Zend\Cache\Storage\AvailableSpaceCapableInterface
- Zend\Cache\Storage\FlushableInterface
- Zend\Cache\Storage\TotalSpaceCapableInterface
Capability | Value |
---|---|
supportedDatatypes | null, boolean, integer, double, string, array (serialized), object (serialized) |
supportedMetadata | internal_key, ttl, hits, size |
minTtl | 1 |
maxTtl | 0 |
staticTtl | true |
ttlPrecision | 1 |
useRequestTime | <ini value of apc.use_request_time> |
expiredRead | false |
namespaceIsPrefix | true |
namespaceSeparator | <Option value of namespace_separator> |
Name | Data Type | Default Value | Description |
---|---|---|---|
namespace_separator | string | ”:” | A separator for the namespace and prefix |
The XCache Adapter¶
The Zend\Cache\Storage\Adapter\XCache adapter stores cache items into shared memory through the required PHP extension XCache.
This adapter implements the following interfaces:
- Zend\Cache\Storage\StorageInterface
- Zend\Cache\Storage\AvailableSpaceCapableInterface
- Zend\Cache\Storage\ClearByNamespaceInterface
- Zend\Cache\Storage\ClearByPrefixInterface
- Zend\Cache\Storage\FlushableInterface
- Zend\Cache\Storage\IterableInterface
- Zend\Cache\Storage\TotalSpaceCapableInterface
Capability | Value |
---|---|
supportedDatatypes | boolean, integer, double, string, array (serialized), object (serialized) |
supportedMetadata | internal_key, size, refcount, hits, ctime, atime, hvalue |
minTtl | 1 |
maxTtl | <ini value of xcache.var_maxttl> |
staticTtl | true |
ttlPrecision | 1 |
useRequestTime | true |
expiredRead | false |
maxKeyLength | 5182 |
namespaceIsPrefix | true |
namespaceSeparator | <Option value of namespace_separator> |
Name | Data Type | Default Value | Description |
---|---|---|---|
namespace_separator | string | ”:” | A separator for the namespace and prefix |
admin_auth | boolean | false | Enable admin authentication by configuration options admin_user and admin_pass This makes XCache administration functions accessible if xcache.admin.enable_auth is enabled without the need of HTTP-Authentication. |
admin_user | string | “” | The username of xcache.admin.user |
admin_pass | string | “” | The password of xcache.admin.pass in plain text |
The ZendServerDisk Adapter¶
This Zend\Cache\Storage\Adapter\ZendServerDisk adapter stores cache items on filesystem through the Zend Server Data Caching API.
This adapter implements the following interfaces:
- Zend\Cache\Storage\StorageInterface
- Zend\Cache\Storage\AvailableSpaceCapableInterface
- Zend\Cache\Storage\ClearByNamespaceInterface
- Zend\Cache\Storage\FlushableInterface
- Zend\Cache\Storage\TotalSpaceCapableInterface
Capability | Value |
---|---|
supportedDatatypes | null, boolean, integer, double, string, array (serialized), object (serialized) |
supportedMetadata | <none> |
minTtl | 1 |
maxTtl | 0 |
maxKeyLength | 0 |
staticTtl | true |
ttlPrecision | 1 |
useRequestTime | false |
expiredRead | false |
namespaceIsPrefix | true |
namespaceSeparator | :: |
The ZendServerShm Adapter¶
The Zend\Cache\Storage\Adapter\ZendServerShm adapter stores cache items in shared memory through the Zend Server Data Caching API.
This adapter implements the following interfaces:
- Zend\Cache\Storage\StorageInterface
- Zend\Cache\Storage\ClearByNamespaceInterface
- Zend\Cache\Storage\FlushableInterface
- Zend\Cache\Storage\TotalSpaceCapableInterface
Capability | Value |
---|---|
supportedDatatypes | null, boolean, integer, double, string, array (serialized), object (serialized) |
supportedMetadata | <none> |
minTtl | 1 |
maxTtl | 0 |
maxKeyLength | 0 |
staticTtl | true |
ttlPrecision | 1 |
useRequestTime | false |
expiredRead | false |
namespaceIsPrefix | true |
namespaceSeparator | :: |
Examples¶
Basic usage
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 | $cache = \Zend\Cache\StorageFactory::factory(array(
'adapter' => array(
'name' => 'filesystem'
),
'plugins' => array(
// Don't throw exceptions on cache errors
'exception_handler' => array(
'throw_exceptions' => false
),
)
));
$key = 'unique-cache-key';
$result = $cache->getItem($key, $success);
if (!$success) {
$result = doExpensiveStuff();
$cache->setItem($key, $result);
}
|
Get multiple rows from db
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 | // Instantiate the cache instance using a namespace for the same type of items
$cache = \Zend\Cache\StorageFactory::factory(array(
'adapter' => array(
'name' => 'filesystem'
// With a namespace we can indicate the same type of items
// -> So we can simple use the db id as cache key
'options' => array(
'namespace' => 'dbtable'
),
),
'plugins' => array(
// Don't throw exceptions on cache errors
'exception_handler' => array(
'throw_exceptions' => false
),
// We store database rows on filesystem so we need to serialize them
'Serializer'
)
));
// Load two rows from cache if possible
$ids = array(1, 2);
$results = $cache->getItems($ids);
if (count($results) < count($ids)) {
// Load rows from db if loading from cache failed
$missingIds = array_diff($ids, array_keys($results));
$missingResults = array();
$query = 'SELECT * FROM dbtable WHERE id IN (' . implode(',', $missingIds) . ')';
foreach ($pdo->query($query, PDO::FETCH_ASSOC) as $row) {
$missingResults[ $row['id'] ] = $row;
}
// Update cache items of the loaded rows from db
$cache->setItems($missingResults);
// merge results from cache and db
$results = array_merge($results, $missingResults);
}
|