Apache Zeta Components Manual :: File Source for manager.php
Source for file manager.php
Documentation is available at manager.php
* File containing the ezcCacheManager class.
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
* http://www.apache.org/licenses/LICENSE-2.0
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* @version //autogentag//
* @license http://www.apache.org/licenses/LICENSE-2.0 Apache License, Version 2.0
* This is the main class of the Cache package. It gives you a handy interface
* to create and manage multiple caches at once. It enables you to configure
* all caches you need in your application in a central place and access them
* on demand in any place in your application.
* The use of ezcCacheManager is not required, but recommended. If you only
* need a few (or maybe just 1) cache instance, you can use and instantiate
* a {@link ezcCacheStorage} class directly.
* Usage example for ezcCacheManager:
* // Some pre-work, needed by the example
* $basePath = dirname( __FILE__ ).'/cache';
* return 'This is a unique ID';
* // Central creation and configuration of the caches
* // The ezcCacheManager just stores the configuration right now and
* // performs sanity checks. The ezcCacheStorage instances
* // will be created on demand, when you use them for the first time
* // Configuration options for a cache (see ezcCacheStorage)
* 'ttl' => 60*60*24*2, // Default would be 1 day, here 2 days
* // Create a cache named "content", that resides in /var/cache/content
* // The cache instance will use the ezcCacheStorageFileArray class
* // to store the cache data. The time-to-live for cache items is set as
* ezcCacheManager::createCache( 'content', $basePath.'/content', 'ezcCacheStorageFileArray', $options );
* // Create another cache, called "template" in /var/cache/templates.
* // This cache will use the ezcCacheStorageFilePlain class to store
* // cache data. It has the same TTL as the cache defined above.
* ezcCacheManager::createCache( 'template', $basePath.'/templates', 'ezcCacheStorageFilePlain', $options );
* // Somewhere in the application you can access the caches
* // Get the instance of the cache called "content"
* // Now the instance of ezcCacheStorageFileArray is created and
* // returned to be used. Next time you access this cache, the created
* // instance will be reused.
* $cache = ezcCacheManager::getCache( 'content' );
* // Instead of using the createCache()/getCache() mechanism you can also
* // create cache on-demand with delayed initialization. You can find
* // information on how to use that in the tutorial.
* // Specify any number of attributes to identify the cache item you want
* // to store. This attributes can be used later to perform operations
* // on a set of cache items, that share a common attribute.
* $attributes = array( 'node' => 2, 'area' => 'admin', 'lang' => 'en-GB' );
* // This function is not part of the Cache package. You have to define
* // unique IDs for your cache items yourself.
* // Initialize the data variable you want to restore
* // Check if data is available in the cache. The restore method returns
* // the cached data, if available, or bool false.
* if ( ( $data = $cache->restore( $id, $attributes ) ) === false )
* // The cache item we tried to restore does not exist, so we have to
* $data = array( 'This is some data', 'and some more data.' );
* // For testing we echo something here...
* echo "No cache data found. Generated some.\n".var_export( $data, true )."\n";
* // Now we store the data in the cache. It will be available through
* // restore, next time the code is reached
* $cache->store( $id, $data, $attributes );
* // We found cache data. Let's echo the information.
* echo "Cache data found.\n".var_export( $data, true )."\n";
* // In some other place you can access the second defined cache.
* $cache = ezcCacheManager::getCache( 'template' );
* // Here we are removing cache items. We do not specify an ID (which would
* // have meant to delete 1 specific cache item), but only an array of
* // attributes. This will result in all cache items to be deleted, that
* // have this attribute assigned.
* $cache->delete( null, array( 'node' => 5 ) );
* @version //autogentag//
* Keeps track of the ezcCacheStorage instances.
* Each cache is created only once per request on the first time it is
* accessed through {@link ezcCacheManager::getCache()}. Until then,
* only its configuration is stored in the
* {@link ezcCacheManager::$configurations} array.
* @var array(int=>ezcCacheStorage)
private static $caches =
array();
* ezcCacheStorage configurations
* Storage to keep track of ezcCacheStorage configurations. For each
* configured cache the configuration is initially stored here.
* {@link ezcCacheStorage} objects are created on first access
* through {@link ezcCacheManager::getCache()}.
* @var array(string=>array(string=>string))
private static $configurations =
array();
* Private. This class has static methods only.
* @see ezcCacheManager::createCache()
* @see ezcCacheManager::getCache()
private function __construct()
* Creates a new cache in the manager.
* This method is used to create a new cache inside the manager.
* Each cache has a unique ID to access it during the application
* runtime. Each location may only be used by 1 cache.
* The $storageClass parameter must be a subclass of
* {@link ezcCacheStorage} and tells the manager which object
* will be used for the cache.
* The $location parameter depends on the kind of {@link ezcCacheStorage}
* used for the cache you create. Usually this is a directory on your
* file system, but may also be e.g. a data source name, if you cache in
* a database or similar. For memory-based storage ({@link ezcCacheStorageApcPlain}
* or {@link ezcCacheStorageMemcachePlain}) it is null, but for
* memory/file hybrid storage ({@link ezcCacheStorageFileApcArray}) it should
* be an existing writeable path.
* The $options array consists of several standard attributes and can
* additionally contain options defined by the {@link ezcCacheStorage}
* class. Standard options are:
* 'ttl' => 60*60*24, // Time-to-life, default: 1 day
* @param string $id ID of the cache to create.
* @param string $location Location to create the cache in. Null for
* memory-based storage and an existing
* writeable path for file or memory/file
* @param string $storageClass Subclass of {@link ezcCacheStorage}.
* @param array(string=>string) $options Options for the cache.
* @throws ezcBaseFileNotFoundException
* If the given location does not exist or is not a
* directory (thrown by sanity checks performed when storing the
* configuration of a cache to ensure the latter calls to
* {@link ezcCacheManager::getCache()} do not fail).
* @throws ezcBaseFilePermissionException
* If the given location is not read/writeable (thrown by sanity
* checks performed when storing the configuration of a cache to
* ensure the latter calls to {@link ezcCacheManager::getCache()}
* @throws ezcCacheUsedLocationException
* If the given location is already in use by another cache.
* @throws ezcCacheInvalidStorageClassException
* If the given storage class does not exist or is no subclass of
public static function createCache( $id, $location =
null, $storageClass, $options =
array() )
// BC for missing location. The location should not be missing.
if ( $location !==
null )
// Unifiy file system locations
if ( substr( $location, 0, 1 ) ===
'/' )
if ( ( $realLocation =
realpath( $location ) ) ===
false )
'Does not exist or is no directory.'
$location =
$realLocation;
// Sanity check double taken locations.
foreach ( self::$configurations as $confId =>
$config )
if ( $config['location'] ===
$location )
throw
new ezcCacheUsedLocationException( $location, $confId );
// Sanity check storage class.
self::$configurations[$id] =
array(
'class' =>
$storageClass,
* Returns the ezcCacheStorage object with the given ID.
* The cache ID has to be defined before using the
* {@link ezcCacheManager::createCache()} method. If no instance of this
* cache does exist yet, it's created on the fly. If one exists, it will
* @param string $id The ID of the cache to return.
* @return ezcCacheStorage The cache with the given ID.
* @throws ezcCacheInvalidIdException
* If the ID of a cache you try to access does not exist. To access
* a cache using this method, it first hast to be created using
* {@link ezcCacheManager::createCache()}.
* @throws ezcBaseFileNotFoundException
* If the storage location does not exist. This should usually not
* happen, since {@link ezcCacheManager::createCache()} already
* performs sanity checks for the cache location. In case this
* exception is thrown, your cache location has been corrupted
* after the cache was configured.
* @throws ezcBaseFileNotFoundException
* If the storage location is not a directory. This should usually
* not happen, since {@link ezcCacheManager::createCache()} already
* performs sanity checks for the cache location. In case this
* exception is thrown, your cache location has been corrupted
* after the cache was configured.
* @throws ezcBaseFilePermissionException
* If the storage location is not writeable. This should usually not
* happen, since {@link ezcCacheManager::createCache()} already
* performs sanity checks for the cache location. In case this
* exception is thrown, your cache location has been corrupted
* after the cache was configured.
* @throws ezcBasePropertyNotFoundException
* If you tried to set a non-existent option value. The accepted
* options depend on the ezcCacheStorage implementation and may
// Look for already existing cache object
if ( !isset
( self::$caches[$id] ) )
// Failed, look for configuration, and if it does not exist, use
// delayed initialization.
if ( !isset
( self::$configurations[$id] ) )
ezcBaseInit::fetchConfig( 'ezcInitCacheManager', $id );
// Check whether delayed initialization actually worked, if not,
if ( !isset
( self::$configurations[$id] ) )
throw
new ezcCacheInvalidIdException( $id );
$class =
self::$configurations[$id]['class'];
self::$caches[$id] =
new $class( self::$configurations[$id]['location'], self::$configurations[$id]['options'] );
return self::$caches[$id];