Apache Zeta Components Manual :: File Source for manager.php

Source for file manager.php

Documentation is available at manager.php

  1. <?php
  2. /**
  3.  * File containing the ezcCacheManager class.
  4.  *
  5.  * Licensed to the Apache Software Foundation (ASF) under one
  6.  * or more contributor license agreements.  See the NOTICE file
  7.  * distributed with this work for additional information
  8.  * regarding copyright ownership.  The ASF licenses this file
  9.  * to you under the Apache License, Version 2.0 (the
  10.  * "License"); you may not use this file except in compliance
  11.  * with the License.  You may obtain a copy of the License at
  12.  * 
  13.  *   http://www.apache.org/licenses/LICENSE-2.0
  14.  * 
  15.  * Unless required by applicable law or agreed to in writing,
  16.  * software distributed under the License is distributed on an
  17.  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  18.  * KIND, either express or implied.  See the License for the
  19.  * specific language governing permissions and limitations
  20.  * under the License.
  21.  *
  22.  * @package Cache
  23.  * @version //autogentag//
  24.  * @license http://www.apache.org/licenses/LICENSE-2.0 Apache License, Version 2.0
  25.  * @filesource
  26.  */
  27.  
  28. /**
  29.  * This is the main class of the Cache package. It gives you a handy interface
  30.  * to create and manage multiple caches at once. It enables you to configure
  31.  * all caches you need in your application in a central place and access them
  32.  * on demand in any place in your application.
  33.  *
  34.  * The use of ezcCacheManager is not required, but recommended. If you only
  35.  * need a few (or maybe just 1) cache instance, you can use and instantiate
  36.  * a {@link ezcCacheStorage} class directly.
  37.  *
  38.  * Usage example for ezcCacheManager:
  39.  * <code>
  40.  * // Some pre-work, needed by the example
  41.  * $basePath = dirname( __FILE__ ).'/cache';
  42.  * function getUniqueId()
  43.  * {
  44.  *     return 'This is a unique ID';
  45.  * }
  46.  *
  47.  * // Central creation and configuration of the caches
  48.  * // The ezcCacheManager just stores the configuration right now and
  49.  * // performs sanity checks. The ezcCacheStorage instances
  50.  * // will be created on demand, when you use them for the first time
  51.  *
  52.  * // Configuration options for a cache (see ezcCacheStorage)
  53.  * $options = array(
  54.  *     'ttl'   => 60*60*24*2,     // Default would be 1 day, here 2 days
  55.  * );
  56.  *
  57.  * // Create a cache named "content", that resides in /var/cache/content
  58.  * // The cache instance will use the ezcCacheStorageFileArray class
  59.  * // to store the cache data. The time-to-live for cache items is set as
  60.  * // defined above.
  61.  * ezcCacheManager::createCache( 'content', $basePath.'/content', 'ezcCacheStorageFileArray', $options );
  62.  *
  63.  * // Create another cache, called "template" in /var/cache/templates.
  64.  * // This cache will use the ezcCacheStorageFilePlain class to store
  65.  * // cache data. It has the same TTL as the cache defined above.
  66.  * ezcCacheManager::createCache( 'template', $basePath.'/templates', 'ezcCacheStorageFilePlain', $options );
  67.  *
  68.  * // Somewhere in the application you can access the caches
  69.  *
  70.  * // Get the instance of the cache called "content"
  71.  * // Now the instance of ezcCacheStorageFileArray is created and
  72.  * // returned to be used. Next time you access this cache, the created
  73.  * // instance will be reused.
  74.  * $cache = ezcCacheManager::getCache( 'content' );
  75.  *
  76.  * // Instead of using the createCache()/getCache() mechanism you can also
  77.  * // create cache on-demand with delayed initialization. You can find
  78.  * // information on how to use that in the tutorial.
  79.  *
  80.  * // Specify any number of attributes to identify the cache item you want
  81.  * // to store. This attributes can be used later to perform operations
  82.  * // on a set of cache items, that share a common attribute.
  83.  * $attributes = array( 'node' => 2, 'area' => 'admin', 'lang' => 'en-GB' );
  84.  *
  85.  * // This function is not part of the Cache package. You have to define
  86.  * // unique IDs for your cache items yourself.
  87.  * $id = getUniqueId();
  88.  *
  89.  * // Initialize the data variable you want to restore
  90.  * $data = '';
  91.  *
  92.  * // Check if data is available in the cache. The restore method returns
  93.  * // the cached data, if available, or bool false.
  94.  * if ( ( $data = $cache->restore( $id, $attributes ) ) === false )
  95.  * {
  96.  *     // The cache item we tried to restore does not exist, so we have to
  97.  *     // generate the data.
  98.  *     $data = array( 'This is some data', 'and some more data.' );
  99.  *     // For testing we echo something here...
  100.  *     echo "No cache data found. Generated some.\n".var_export( $data, true )."\n";
  101.  *     // Now we store the data in the cache. It will be available through
  102.  *     // restore, next time the code is reached
  103.  *     $cache->store( $id, $data, $attributes );
  104.  * }
  105.  * else
  106.  * {
  107.  *     // We found cache data. Let's echo the information.
  108.  *     echo "Cache data found.\n".var_export( $data, true )."\n";
  109.  * }
  110.  *
  111.  * // In some other place you can access the second defined cache.
  112.  * $cache = ezcCacheManager::getCache( 'template' );
  113.  *
  114.  * // Here we are removing cache items. We do not specify an ID (which would
  115.  * // have meant to delete 1 specific cache item), but only an array of
  116.  * // attributes. This will result in all cache items to be deleted, that
  117.  * // have this attribute assigned.
  118.  * $cache->delete( null, array( 'node' => 5 ) );
  119.  * </code>
  120.  *
  121.  * @package Cache
  122.  * @version //autogentag//
  123.  * @mainclass
  124.  */
  125. {
  126.     /**
  127.      * Keeps track of the ezcCacheStorage instances.
  128.      * Each cache is created only once per request on the first time it is
  129.      * accessed through {@link ezcCacheManager::getCache()}. Until then,
  130.      * only its configuration is stored in the
  131.      * {@link ezcCacheManager::$configurations} array.
  132.      *
  133.      * @var array(int=>ezcCacheStorage) 
  134.      */
  135.     private static $caches array();
  136.  
  137.     /**
  138.      * ezcCacheStorage configurations
  139.      * Storage to keep track of ezcCacheStorage configurations. For each
  140.      * configured cache the configuration is initially stored here.
  141.      * {@link ezcCacheStorage} objects are created on first access
  142.      * through {@link ezcCacheManager::getCache()}.
  143.      *
  144.      * @var array(string=>array(string=>string)) 
  145.      */
  146.     private static $configurations array();
  147.  
  148.     /**
  149.      * Private. This class has static methods only.
  150.      *
  151.      * @see ezcCacheManager::createCache()
  152.      * @see ezcCacheManager::getCache()
  153.      */
  154.     private function __construct()
  155.     {
  156.     }
  157.  
  158.     /**
  159.      * Creates a new cache in the manager.
  160.      * This method is used to create a new cache inside the manager.
  161.      * Each cache has a unique ID to access it during the application
  162.      * runtime. Each location may only be used by 1 cache.
  163.      *
  164.      * The $storageClass parameter must be a subclass of
  165.      * {@link ezcCacheStorage} and tells the manager which object
  166.      * will be used for the cache.
  167.      *
  168.      * The $location parameter depends on the kind of {@link ezcCacheStorage}
  169.      * used for the cache you create. Usually this is a directory on your
  170.      * file system, but may also be e.g. a data source name, if you cache in
  171.      * a database or similar. For memory-based storage ({@link ezcCacheStorageApcPlain}
  172.      * or {@link ezcCacheStorageMemcachePlain}) it is null, but for
  173.      * memory/file hybrid storage ({@link ezcCacheStorageFileApcArray}) it should
  174.      * be an existing writeable path.
  175.      *
  176.      * The $options array consists of several standard attributes and can
  177.      * additionally contain options defined by the {@link ezcCacheStorage}
  178.      * class. Standard options are:
  179.      *
  180.      * <code>
  181.      * array(
  182.      *      'ttl'   => 60*60*24,    // Time-to-life, default: 1 day
  183.      * );
  184.      * </code>
  185.      *
  186.      * @param string $id                     ID of the cache to create.
  187.      * @param string $location               Location to create the cache in. Null for
  188.      *                                        memory-based storage and an existing
  189.      *                                        writeable path for file or memory/file
  190.      *                                        storage.
  191.      * @param string $storageClass           Subclass of {@link ezcCacheStorage}.
  192.      * @param array(string=>string) $options Options for the cache.
  193.      * @return void 
  194.      *
  195.      * @throws ezcBaseFileNotFoundException
  196.      *          If the given location does not exist or is not a
  197.      *          directory (thrown by sanity checks performed when storing the
  198.      *          configuration of a cache to ensure the latter calls to
  199.      *          {@link ezcCacheManager::getCache()} do not fail).
  200.      * @throws ezcBaseFilePermissionException
  201.      *          If the given location is not read/writeable (thrown by sanity
  202.      *          checks performed when storing the configuration of a cache to
  203.      *          ensure the latter calls to {@link ezcCacheManager::getCache()}
  204.      *          do not fail).
  205.      * @throws ezcCacheUsedLocationException
  206.      *          If the given location is already in use by another cache.
  207.      * @throws ezcCacheInvalidStorageClassException
  208.      *          If the given storage class does not exist or is no subclass of
  209.      *          ezcCacheStorage.
  210.      */
  211.     public static function createCache$id$location null$storageClass$options array() )
  212.     {
  213.         // BC for missing location. The location should not be missing.
  214.         if $location !== null )
  215.         {
  216.             // Unifiy file system locations
  217.             if substr$location0=== '/' )
  218.             {
  219.                 // If non-existent
  220.                 if ( ( $realLocation realpath$location ) ) === false )
  221.                 {
  222.                     throw new ezcBaseFileNotFoundException(
  223.                         $location,
  224.                         'cache location',
  225.                         'Does not exist or is no directory.'
  226.                     );
  227.                 }
  228.                 $location $realLocation;
  229.             }
  230.  
  231.             // Sanity check double taken locations.
  232.             foreach self::$configurations as $confId => $config )
  233.             {
  234.                 if $config['location'=== $location )
  235.                 {
  236.                     throw new ezcCacheUsedLocationException$location$confId );
  237.                 }
  238.             }
  239.         }
  240.  
  241.         // Sanity check storage class.
  242.         if !ezcBaseFeatures::classExists$storageClass || !is_subclass_of$storageClass'ezcCacheStorage' ) )
  243.         {
  244.             throw new ezcCacheInvalidStorageClassException$storageClass );
  245.         }
  246.         self::$configurations[$idarray(
  247.             'location' => $location,
  248.             'class'    => $storageClass,
  249.             'options'  => $options,
  250.         );
  251.     }
  252.  
  253.     /**
  254.      * Returns the ezcCacheStorage object with the given ID.
  255.      * The cache ID has to be defined before using the
  256.      * {@link ezcCacheManager::createCache()} method. If no instance of this
  257.      * cache does exist yet, it's created on the fly. If one exists, it will
  258.      * be reused.
  259.      *
  260.      * @param string $id       The ID of the cache to return.
  261.      * @return ezcCacheStorage The cache with the given ID.
  262.      *
  263.      * @throws ezcCacheInvalidIdException
  264.      *          If the ID of a cache you try to access does not exist. To access
  265.      *          a cache using this method, it first hast to be created using
  266.      *          {@link ezcCacheManager::createCache()}.
  267.      * @throws ezcBaseFileNotFoundException
  268.      *          If the storage location does not exist. This should usually not
  269.      *          happen, since {@link ezcCacheManager::createCache()} already
  270.      *          performs sanity checks for the cache location. In case this
  271.      *          exception is thrown, your cache location has been corrupted
  272.      *          after the cache was configured.
  273.      * @throws ezcBaseFileNotFoundException
  274.      *          If the storage location is not a directory. This should usually
  275.      *          not happen, since {@link ezcCacheManager::createCache()} already
  276.      *          performs sanity checks for the cache location. In case this
  277.      *          exception is thrown, your cache location has been corrupted
  278.      *          after the cache was configured.
  279.      * @throws ezcBaseFilePermissionException
  280.      *          If the storage location is not writeable. This should usually not
  281.      *          happen, since {@link ezcCacheManager::createCache()} already
  282.      *          performs sanity checks for the cache location. In case this
  283.      *          exception is thrown, your cache location has been corrupted
  284.      *          after the cache was configured.
  285.      * @throws ezcBasePropertyNotFoundException
  286.      *          If you tried to set a non-existent option value. The accepted
  287.      *          options depend on the ezcCacheStorage implementation and may
  288.      *          vary.
  289.      */
  290.     public static function getCache$id )
  291.     {
  292.         // Look for already existing cache object
  293.         if !issetself::$caches[$id) )
  294.         {
  295.             // Failed, look for configuration, and if it does not exist, use
  296.             // delayed initialization.
  297.             if !issetself::$configurations[$id) )
  298.             {
  299.                 ezcBaseInit::fetchConfig'ezcInitCacheManager'$id );
  300.             }
  301.             // Check whether delayed initialization actually worked, if not,
  302.             // throw an exception
  303.             if !issetself::$configurations[$id) )
  304.             {
  305.                 throw new ezcCacheInvalidIdException$id );
  306.             }
  307.             $class self::$configurations[$id]['class'];
  308.             self::$caches[$idnew $classself::$configurations[$id]['location']self::$configurations[$id]['options');
  309.         }
  310.         return self::$caches[$id];
  311.     }
  312. }
  313. ?>
Documentation generated by phpDocumentor 1.4.3