Apache Zeta Components - high quality PHP components

Apache Zeta Components Manual :: Docs For Class ezcCacheManager

Cache::ezcCacheManager

Class ezcCacheManager

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 ezcCacheStorage class directly.

Usage example for ezcCacheManager:

  1.  // Some pre-work, needed by the example
  2.  $basePath = dirname( __FILE__ ).'/cache';
  3.  function getUniqueId()
  4.  {
  5.      return 'This is a unique ID';
  6.  }
  7.  
  8.  // Central creation and configuration of the caches
  9.  // The ezcCacheManager just stores the configuration right now and
  10.  // performs sanity checks. The ezcCacheStorage instances
  11.  // will be created on demand, when you use them for the first time
  12.  
  13.  // Configuration options for a cache (see ezcCacheStorage)
  14.  $options = array(
  15.      'ttl'   => 60*60*24*2,     // Default would be 1 day, here 2 days
  16.  );
  17.  
  18.  // Create a cache named "content", that resides in /var/cache/content
  19.  // The cache instance will use the ezcCacheStorageFileArray class
  20.  // to store the cache data. The time-to-live for cache items is set as
  21.  // defined above.
  22.  ezcCacheManager::createCache( 'content', $basePath.'/content', 'ezcCacheStorageFileArray', $options );
  23.  
  24.  // Create another cache, called "template" in /var/cache/templates.
  25.  // This cache will use the ezcCacheStorageFilePlain class to store
  26.  // cache data. It has the same TTL as the cache defined above.
  27.  ezcCacheManager::createCache( 'template', $basePath.'/templates', 'ezcCacheStorageFilePlain', $options );
  28.  
  29.  // Somewhere in the application you can access the caches
  30.  
  31.  // Get the instance of the cache called "content"
  32.  // Now the instance of ezcCacheStorageFileArray is created and
  33.  // returned to be used. Next time you access this cache, the created
  34.  // instance will be reused.
  35.  $cache = ezcCacheManager::getCache( 'content' );
  36.  
  37.  // Instead of using the createCache()/getCache() mechanism you can also
  38.  // create cache on-demand with delayed initialization. You can find
  39.  // information on how to use that in the tutorial.
  40.  
  41.  // Specify any number of attributes to identify the cache item you want
  42.  // to store. This attributes can be used later to perform operations
  43.  // on a set of cache items, that share a common attribute.
  44.  $attributes = array( 'node' => 2, 'area' => 'admin', 'lang' => 'en-GB' );
  45.  
  46.  // This function is not part of the Cache package. You have to define
  47.  // unique IDs for your cache items yourself.
  48.  $id = getUniqueId();
  49.  
  50.  // Initialize the data variable you want to restore
  51.  $data = '';
  52.  
  53.  // Check if data is available in the cache. The restore method returns
  54.  // the cached data, if available, or bool false.
  55.  if ( ( $data = $cache->restore( $id, $attributes ) ) === false )
  56.  {
  57.      // The cache item we tried to restore does not exist, so we have to
  58.      // generate the data.
  59.      $data = array( 'This is some data', 'and some more data.' );
  60.      // For testing we echo something here...
  61.      echo "No cache data found. Generated some.\n".var_export( $data, true )."\n";
  62.      // Now we store the data in the cache. It will be available through
  63.      // restore, next time the code is reached
  64.      $cache->store( $id, $data, $attributes );
  65.  }
  66.  else
  67.  {
  68.      // We found cache data. Let's echo the information.
  69.      echo "Cache data found.\n".var_export( $data, true )."\n";
  70.  }
  71.  
  72.  // In some other place you can access the second defined cache.
  73.  $cache = ezcCacheManager::getCache( 'template' );
  74.  
  75.  // Here we are removing cache items. We do not specify an ID (which would
  76.  // have meant to delete 1 specific cache item), but only an array of
  77.  // attributes. This will result in all cache items to be deleted, that
  78.  // have this attribute assigned.
  79.  $cache->delete( null, array( 'node' => 5 ) );

Source for this file: /Cache/src/manager.php

Version:   //autogentag//

Method Summary

public static void createCache( $id , [ $location = null] , $storageClass , [ $options = array()] )
Creates a new cache in the manager.
public static ezcCacheStorage getCache( $id )
Returns the ezcCacheStorage object with the given ID.

Methods

createCache

static void createCache( string $id , [string $location = null] , string $storageClass , [array(string=>string) $options = array()] )

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 ezcCacheStorage and tells the manager which object will be used for the cache.

The $location parameter depends on the kind of 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 (ezcCacheStorageApcPlain or ezcCacheStorageMemcachePlain) it is null, but for memory/file hybrid storage (ezcCacheStorageFileApcArray) it should be an existing writeable path.

The $options array consists of several standard attributes and can additionally contain options defined by the ezcCacheStorage class. Standard options are:

  1.  array(
  2.       'ttl'   => 60*60*24,    // Time-to-life, default: 1 day
  3.  );
Parameters:
Name Type Description
$id string ID of the cache to create.
$location string Location to create the cache in. Null for memory-based storage and an existing writeable path for file or memory/file storage.
$storageClass string Subclass of ezcCacheStorage.
$options array(string=>string) Options for the cache.
Exceptions:
Type Description
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 ezcCacheManager::getCache() do not fail).
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 ezcCacheManager::getCache() do not fail).
ezcCacheInvalidStorageClassException If the given storage class does not exist or is no subclass of ezcCacheStorage.
ezcCacheUsedLocationException If the given location is already in use by another cache.

getCache

static ezcCacheStorage getCache( string $id )

Returns the ezcCacheStorage object with the given ID.

The cache ID has to be defined before using the ezcCacheManager::createCache() method. If no instance of this cache does exist yet, it's created on the fly. If one exists, it will be reused.

Parameters:
Name Type Description
$id string The ID of the cache to return.
Exceptions:
Type Description
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 ezcCacheManager::createCache().
ezcBasePropertyNotFoundException If you tried to set a non-existent option value. The accepted options depend on the ezcCacheStorage implementation and may vary.
ezcBaseFileNotFoundException If the storage location does not exist. This should usually not happen, since 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.
ezcBaseFileNotFoundException If the storage location is not a directory. This should usually not happen, since 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.
ezcBaseFilePermissionException If the storage location is not writeable. This should usually not happen, since 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.
Documentation generated by phpDocumentor 1.4.3