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 extendZend\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 thesetOptions()
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 theZend\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 theZend\Cache\Storage\Adapter\*
classes.To make life easier, the
Zend\Cache\StorageFactory
comes with afactory
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 thesetOptions()
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 theZend\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 returnsmixed
value of item.If item can’t load set parameter $success to
false
and returnsnull
.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 Redis Adapter¶
The
Zend\Cache\Storage\Adapter\Redis
adapter stores cache items over the redis protocol. It’s using the required PHP extension redis.This adapter implements the following interfaces:
Zend\Cache\Storage\FlushableInterface
Zend\Cache\Storage\TotalSpaceCapableInterface
Capability | Value |
---|---|
supportedDatatypes | 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 |
---|---|---|---|
database | integer |
0 | Set database identifier |
lib_option | array |
[] |
Associative array of redis options were the array key is the option name |
namespace_separator | string |
“:” | A separator for the namespace and prefix |
password | string |
“” | Set password |
persistent_id | string |
Set persistent id (name of the connection, leave blank to not use a persistent connection) | |
resource_manager | string |
Set the redis resource manager to use | |
server |
|
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 MongoDB Adapter¶
Capability | Value |
---|---|
supportedDatatypes | null , boolean , integer , double , string , array |
supportedMetadata | _id |
minTtl | 0 |
maxTtl | 0 |
staticTtl | true |
ttlPrecision | 1 |
useRequestTime | false |
expiredRead | false |
maxKeyLength | 255 |
namespaceIsPrefix | true |
namespaceSeparator | <Option value of namespace_separator> |
Name | Data Type | Default Value | Description |
---|---|---|---|
lib_option | array |
|
|
namespace_separator | string |
“:” | A separator for the namespace and prefix |
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 This makes XCache administration functions accessible if |
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);
}
|