1  <?php
  2  /* Copyright (c) 2012, Geert Bergman (geert@scrivo.nl)
  3   * All rights reserved.
  4   *
  5   * Redistribution and use in source and binary forms, with or without
  6   * modification, are permitted provided that the following conditions are met:
  7   *
  8   * 1. Redistributions of source code must retain the above copyright notice,
  9   *    this list of conditions and the following disclaimer.
 10   * 2. Redistributions in binary form must reproduce the above copyright notice,
 11   *    this list of conditions and the following disclaimer in the documentation
 12   *    and/or other materials provided with the distribution.
 13   * 3. Neither the name of "Scrivo" nor the names of its contributors may be
 14   *    used to endorse or promote products derived from this software without
 15   *    specific prior written permission.
 16   *
 17   * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 18   * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 19   * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 20   * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
 21   * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 22   * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 23   * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 24   * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 25   * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 26   * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 27   * POSSIBILITY OF SUCH DAMAGE.
 28   *
 29   * $Id: Cache.php 841 2013-08-19 22:19:47Z geert $
 30   */
 31  
 32  /**
 33   * Implementation of the \Scrivo\Cache interface.
 34   */
 35  
 36  namespace Scrivo;
 37  
 38  /**
 39   * The Scrivo cache interface defines the interface for cache classes. These
 40   * cache classes can be used to hold Scrivo data in shared storage between
 41   * requests and processes.
 42   */
 43  interface Cache {
 44  
 45      /**
 46       * Constant to indicate that a value was succesfully stored in the cache.
 47       */
 48      const DATA_STORED 1;
 49  
 50      /**
 51       * Constant to indicate that a value was not stored in the cache because
 52       * the entry was already taken.
 53       */
 54      const CACHE_SLAM 2;
 55  
 56      /**
 57       * Constant to indicate that a value was not stored in the cache because
 58       * there was not enough storage available.
 59       */
 60      const NO_SPACE 3;
 61  
 62      /**
 63       * Store a variable in the cache.
 64       *
 65       * Store any serializable variable in the cache. Note that it is not
 66       * possible to overwrite an existing entry (cache slam). Such an event
 67       * will not raise an error but the function will report it.
 68       *
 69       * So subseqent calls to store should not made when the data to store
 70       * changes between calls. If you activily want to store cache entries
 71       * consider using overwrite() or first delete the entry before you store
 72       * it.
 73       *
 74       * Not to allow cache slams was a design decision because PHP does not
 75       * allow thread save access to files. Thus when implementing a file
 76       * cache disallowing a store request because an other thread is writing
 77       * is considered expected behavoir.
 78       *
 79       * @param \Scrivo\String $key A cache unique name for the key.
 80       * @param mixed $val The (serializable) variabele to strore.
 81       * @param int $ttl Time to live in seconds.
 82       *
 83       * @return int DATA_STORED if the variable was succesfully stored,
 84       *       CACHE_SLAM if key already exists or NO_SPACE if there is not
 85       *    enough space left to store the value.
 86       *
 87       * @throws \Scrivo\SystemException When trying to store a NULL value.
 88       */
 89      public function store(\Scrivo\String $key$val$ttl=3600);
 90  
 91      /**
 92       * Store a variable in the cache, overwrite it if it already exists.
 93       *
 94       * Store any serializable variable in the cache. It is guaranteed that
 95       * the data will be written. But note that it is not guaranteed that the
 96       * next fetch will retrieve this value.
 97       *
 98       * @param \Scrivo\String $key A cache unique name for the key.
 99       * @param mixed $val The (serializable) variabele to strore.
100       * @param int $ttl Time to live in seconds.
101       *
102       * @return int DATA_STORED if the variable was succesfully stored or
103       *       NO_SPACE if there is not enough space left to store the value.
104       *
105       * @throws \Scrivo\SystemException When trying to store a NULL value.
106       */
107      public function overwrite(\Scrivo\String $key$val$ttl=3600);
108  
109      /**
110       * Delete/remove a cache entry.
111       *
112       * @param \Scrivo\String $key A cache unique name for the key.
113       */
114      public function delete(\Scrivo\String $key);
115  
116      /**
117       * Retrieve a value from the cache.
118       *
119       * @param \Scrivo\String $key The key for which to retrieve the value.
120       *
121       * @return mixed The value of the stored variable or NULL if the key
122       *   does not exists or is expired.
123       */
124      public function fetch(\Scrivo\String $key);
125  
126      /**
127       * List all entries in the cache.
128       *
129       * This method returns an array in which the cache keys are the keys of
130       * the array entries and the data of each entry is an object of type
131       * stdClass that contains at least the following properties:
132       *
133       * * accessed: the access time
134       * * expires: the expiration time
135       * * created: the creation time
136       * * size: the size of the entry
137       *
138       * @return object[] A array of objects that describe the current cache
139       *    entries.
140       */
141      public function entryList();
142  
143  }
144  

Documentation generated by phpDocumentor 2.0.0a12 and ScrivoDocumentor on August 29, 2013