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

Source for file storage.php

Documentation is available at storage.php

  1. <?php
  2. /**
  3.  * File containing the ezcCacheStorage 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 abstract base class for all cache storages. It provides
  30.  * the interface to be implemented by a cache backend as abstract methods.
  31.  * For your convenience it contains some methods you can utilize to create your
  32.  * own storage implementation (e.g. for storing cache data into a database).
  33.  *
  34.  * Implementations of ezcCacheStorage can be used with the
  35.  * {@link ezcCacheManager} or on their own. If you want to implement a cache
  36.  * storage backend that stores cache data in a file on your harddisk, there
  37.  * is an extended version of ezcCacheStorage, {@link ezcCacheStorageFile},
  38.  * which already implements large parts of the API and leaves only
  39.  * very few work for you to do. The descendant class {@link ezcCacheStorageMemory}
  40.  * is a base class for storage using memory.
  41.  *
  42.  * For example code of using a cache storage, see {@link ezcCacheManager}.
  43.  *
  44.  * The Cache package already contains several implementations of
  45.  * {@link ezcCacheStorageFile}:
  46.  *
  47.  * - {@link ezcCacheStorageFileArray}
  48.  * - {@link ezcCacheStorageFileEvalArray}
  49.  * - {@link ezcCacheStorageFilePlain}
  50.  *
  51.  * Implementations of {@link ezcCacheStorageMemory}:
  52.  *
  53.  * - {@link ezcCacheStorageMemcachePlain}
  54.  * - {@link ezcCacheStorageApcPlain}
  55.  * - {@link ezcCacheStorageFileApcArray}
  56.  *
  57.  * @property ezcCacheStorageOptions $options 
  58.  *            Options for the cache storage. Which options are
  59.  *            supported depends on the specific implementation of the
  60.  *            ezcCacheStorage.
  61.  * @property string $location 
  62.  *            The location the cache resides in.
  63.  *
  64.  * @package Cache
  65.  * @version //autogentag//
  66.  */
  67. abstract class ezcCacheStorage
  68. {
  69.     /**
  70.      * Container to hold the properties
  71.      *
  72.      * @var array(string=>mixed) 
  73.      */
  74.     protected $properties;
  75.  
  76.     /**
  77.      * Creates a new cache storage in the given location.
  78.      * Creates a new cache storage for a given location. The location can
  79.      * differ for each ezcCacheStorage implementation, but will most likely
  80.      * be a filesystem path to a directory where cache data is stored in. The
  81.      * location is null for memory storage and an existing writeable path
  82.      * for file or memory/file storage.
  83.      *
  84.      * Per default there is only 1 common option for all ezcCacheStorage
  85.      * classes, which is the 'ttl' ( Time-To-Life ). This is per default set
  86.      * to 1 day. Specific ezcCacheStorage implementations can have
  87.      * additional options.
  88.      *
  89.      * @param string $location               Path to the cache location. Null for
  90.      *                                        memory-based storage and an existing
  91.      *                                        writeable path for file or memory/file
  92.      *                                        storage.
  93.      * @param array(string=>string) $options Options for the cache.
  94.      *
  95.      * @throws ezcBaseFileNotFoundException
  96.      *          If the storage location does not exist. This should usually not
  97.      *          happen, since {@link ezcCacheManager::createCache()} already
  98.      *          performs sanity checks for the cache location. In case this
  99.      *          exception is thrown, your cache location has been corrupted
  100.      *          after the cache was configured.
  101.      * @throws ezcBaseFileNotFoundException
  102.      *          If the storage location is not a directory. This should usually
  103.      *          not happen, since {@link ezcCacheManager::createCache()} already
  104.      *          performs sanity checks for the cache location. In case this
  105.      *          exception is thrown, your cache location has been corrupted
  106.      *          after the cache was configured.
  107.      * @throws ezcBaseFilePermissionException
  108.      *          If the storage location is not writeable. This should usually not
  109.      *          happen, since {@link ezcCacheManager::createCache()} already
  110.      *          performs sanity checks for the cache location. In case this
  111.      *          exception is thrown, your cache location has been corrupted
  112.      *          after the cache was configured.
  113.      * @throws ezcBasePropertyNotFoundException
  114.      *          If you tried to set a non-existent option value. The accepted
  115.      *          options depend on the ezcCacheStorage implementation and may
  116.      *          vary.
  117.      */
  118.     public function __construct$location$options array() )
  119.     {
  120.         $this->properties['location'substr$location-=== '/' $location $location '/';
  121.         $this->validateLocation();
  122.         $this->properties['options'new ezcCacheStorageOptions$options );
  123.     }
  124.  
  125.     /**
  126.      * Store data to the cache storage.
  127.      * This method stores the given cache data into the cache, assigning the
  128.      * ID given to it.
  129.      *
  130.      * The type of cache data which is expected by a ezcCacheStorage depends on
  131.      * its implementation. In most cases strings and arrays will be accepted,
  132.      * in some rare cases only strings might be accepted.
  133.      *
  134.      * Using attributes you can describe your cache data further. This allows
  135.      * you to deal with multiple cache data at once later. Some ezcCacheStorage
  136.      * implementations also use the attributes for storage purposes. Attributes
  137.      * form some kind of "extended ID".
  138.      *
  139.      * @param string $id                        The item ID.
  140.      * @param mixed $data                       The data to store.
  141.      * @param array(string=>string) $attributes Attributes that describe the
  142.      *                                           cached data.
  143.      *
  144.      * @return string           The ID of the newly cached data.
  145.      *
  146.      * @throws ezcBaseFilePermissionException
  147.      *          If an already existsing cache file could not be unlinked to
  148.      *          store the new data (may occur, when a cache item's TTL
  149.      *          has expired and the file should be stored with more actual
  150.      *          data). This exception means most likely that your cache directory
  151.      *          has been corrupted by external influences (file permission
  152.      *          change).
  153.      * @throws ezcBaseFilePermissionException
  154.      *          If the directory to store the cache file could not be created.
  155.      *          This exception means most likely that your cache directory
  156.      *          has been corrupted by external influences (file permission
  157.      *          change).
  158.      * @throws ezcBaseFileIoException
  159.      *          If an error occured while writing the data to the cache. If this
  160.      *          exception occurs, a serious error occured and your storage might
  161.      *          be corruped (e.g. broken network connection, file system broken,
  162.      *          ...).
  163.      * @throws ezcCacheInvalidDataException
  164.      *          If the data submitted can not be handled by the implementation
  165.      *          of {@link ezcCacheStorage}. Most implementations can not
  166.      *          handle objects and resources.
  167.      */
  168.     abstract public function store$id$data$attributes array() );
  169.  
  170.     /**
  171.      * Restore data from the cache.
  172.      * Restores the data associated with the given cache and
  173.      * returns it. Please see {@link ezcCacheStorage::store()}
  174.      * for more detailed information of cachable datatypes.
  175.      *
  176.      * During access to cached data the caches are automatically
  177.      * expired. This means, that the ezcCacheStorage object checks
  178.      * before returning the data if it's still actual. If the cache
  179.      * has expired, data will be deleted and false is returned.
  180.      *
  181.      * You should always provide the attributes you assigned, although
  182.      * the cache storages must be able to find a cache ID even without
  183.      * them. BEWARE: Finding cache data only by ID can be much
  184.      * slower than finding it by ID and attributes.
  185.      *
  186.      * @param string $id                        The item ID.
  187.      * @param array(string=>string) $attributes Attributes that describe the
  188.      *                                           cached data.
  189.      * @param bool $search                      Whether to search for items
  190.      *                                           if not found directly. Default is
  191.      *                                           false.
  192.      *
  193.      * @return mixed The cached data on success, otherwise false.
  194.      *
  195.      * @throws ezcBaseFilePermissionException
  196.      *          If an already existsing cache file could not be unlinked.
  197.      *          This exception means most likely that your cache directory
  198.      *          has been corrupted by external influences (file permission
  199.      *          change).
  200.      */
  201.     abstract public function restore$id$attributes array()$search false );
  202.  
  203.     /**
  204.      * Delete data from the cache.
  205.      * Purges the cached data for a given ID and or attributes. Using an ID
  206.      * purges only the cache data for just this ID.
  207.      *
  208.      * Additional attributes provided will matched additionally. This can give
  209.      * you an immense speed improvement against just searching for ID ( see
  210.      * {@link ezcCacheStorage::restore()} ).
  211.      *
  212.      * If you only provide attributes for deletion of cache data, all cache
  213.      * data matching these attributes will be purged.
  214.      *
  215.      * @param string $id                        The item ID.
  216.      * @param array(string=>string) $attributes Attributes that describe the
  217.      *                                           cached data.
  218.      * @param bool $search                      Whether to search for items
  219.      *                                           if not found directly. Default is
  220.      *                                           false.
  221.      *
  222.      * @throws ezcBaseFilePermissionException
  223.      *          If an already existsing cache file could not be unlinked.
  224.      *          This exception means most likely that your cache directory
  225.      *          has been corrupted by external influences (file permission
  226.      *          change).
  227.      */
  228.     abstract public function delete$id null$attributes array()$search false );
  229.  
  230.     /**
  231.     * Return the number of items in the cache matching a certain criteria.
  232.     * This method determines if cache data described by the given ID and/or
  233.     * attributes exists. It returns the number of cache data items found.
  234.     *
  235.     * @param string $id                        The item ID.
  236.     * @param array(string=>string) $attributes Attributes that describe the item
  237.     * @return int The number of cache data items found matching the criteria
  238.     */
  239.     abstract public function countDataItems$id null$attributes array() );
  240.  
  241.     /**
  242.      * Returns the time ( in seconds ) that remains for a cache object,
  243.      * before it gets outdated. In case the cache object is already
  244.      * outdated or does not exist, this method returns 0.
  245.      *
  246.      * @param string $id                        The item ID.
  247.      * @param array(string=>string) $attributes Attributes that describe the
  248.      * @access public
  249.      * @return int The remaining lifetime ( 0 if nonexists or outdated ).
  250.      */
  251.     abstract public function getRemainingLifetime$id$attributes array() );
  252.  
  253.     /**
  254.      * Checks if the location property is valid.
  255.      */
  256.     abstract protected function validateLocation();
  257.  
  258.     /**
  259.      * Returns the location.
  260.      *
  261.      * Returns the location the current storage resides in. The
  262.      * $location attribute has no setter, since it can only be set during
  263.      * construction.
  264.      *
  265.      * @return string The location of this storage.
  266.      *
  267.      * @apichange Use $stack->location instead.
  268.      */
  269.     public function getLocation()
  270.     {
  271.         return $this->properties['location'];
  272.     }
  273.  
  274.     /**
  275.      * Return the currently set options.
  276.      *
  277.      * Return the currently set options. The options are returned on an array
  278.      * that has the same format as the one passed to
  279.      * {@link ezcCacheStorage::setOptions()}. The possible options for a storage
  280.      * depend on its implementation.
  281.      *
  282.      * @return ezcCacheStorageOptions The options
  283.      *
  284.      * @apichange Use $storage->options instead.
  285.      */
  286.     public function getOptions()
  287.     {
  288.         return $this->properties['options'];
  289.     }
  290.  
  291.     /**
  292.      * Set new options.
  293.      *
  294.      * This method allows you to change the options of a cache storage. Change
  295.      * of options take effect directly after this method has been called. The
  296.      * available options depend on the ezcCacheStorage implementation. All
  297.      * implementations have to offer the following options:
  298.      *
  299.      * - ttl        The time-to-life. After this time span, a cache item becomes
  300.      *              invalid and will be purged. The
  301.      *              {@link ezcCacheStorage::restore()} method will then return
  302.      *              false.
  303.      * - extension  The "extension" for your cache items. This is usually the
  304.      *              file name extension, when you deal with file system based
  305.      *              caches or e.g. a database ID extension.
  306.      *
  307.      * @param ezcCacheStorageOptions $options The options to set.
  308.      *
  309.      * @throws ezcBasePropertyNotFoundException
  310.      *          If you tried to set a non-existent option value. The accepted
  311.      *          options depend on the ezcCacheStorage implementation and may
  312.      *          vary.
  313.      * @throws ezcBaseValueException
  314.      *          If the value is not valid for the desired option.
  315.      * @throws ezcBaseValueException
  316.      *          If you submit neither an array nor an instance of
  317.      *          ezcCacheStorageOptions.
  318.      *
  319.      * @apichange Use $storage->options instead.
  320.      */
  321.     public function setOptions$options )
  322.     {
  323.         if is_array$options ) )
  324.         {
  325.             $this->properties['options']->merge$options );
  326.         }
  327.         else if $options instanceof ezcCacheStorageOptions )
  328.         {
  329.             $this->properties['options'$options;
  330.         }
  331.         else
  332.         {
  333.             throw new ezcBaseValueException"options"$options"instance of ezcCacheStorageOptions" );
  334.         }
  335.     }
  336.  
  337.  
  338.     /**
  339.      * Property read access.
  340.      *
  341.      * @throws ezcBasePropertyNotFoundException
  342.      *          If the the desired property is not found.
  343.      *
  344.      * @param string $propertyName Name of the property.
  345.      * @return mixed Value of the property or null.
  346.      * @ignore
  347.      */
  348.     public function __get$propertyName )
  349.     {
  350.         if $this->__isset$propertyName ) )
  351.         {
  352.             return $this->properties[$propertyName];
  353.         }
  354.         throw new ezcBasePropertyNotFoundException$propertyName );
  355.     }
  356.  
  357.     /**
  358.      * Property write access.
  359.      *
  360.      * @param string $propertyName Name of the property.
  361.      * @param mixed $val  The value for the property.
  362.      *
  363.      * @throws ezcBaseValueException
  364.      *          If the value for the property options is not an instance of
  365.      *          ezcCacheStorageOptions.
  366.      * @ignore
  367.      */
  368.     public function __set$propertyName$val )
  369.     {
  370.         switch $propertyName )
  371.         {
  372.             case 'options':
  373.                 if !$val instanceof ezcCacheStorageOptions ) )
  374.                 {
  375.                     throw new ezcBaseValueException$propertyName$val'instance of ezcCacheStorageOptions' );
  376.                 }
  377.                 break;
  378.             case 'location':
  379.                 throw new ezcBasePropertyPermissionException(
  380.                     $propertyName,
  381.                     ezcBasePropertyPermissionException::READ
  382.                 );
  383.             default:
  384.                 throw new ezcBasePropertyNotFoundException$propertyName );
  385.         }
  386.         $this->properties[$propertyName$val;
  387.     }
  388.  
  389.     /**
  390.      * Property isset access.
  391.      *
  392.      * @param string $propertyName Name of the property.
  393.      * @return bool True is the property is set, otherwise false.
  394.      * @ignore
  395.      */
  396.     public function __isset$propertyName )
  397.     {
  398.         return array_key_exists$propertyName$this->properties );
  399.     }
  400. }
  401. ?>
Documentation generated by phpDocumentor 1.4.3