Adding Psr\Cache proposal

proposed/psr-cache.md

@@ -0,0 +1,169 @@
+# Specification
+
+## 1.1 Definitions
+
+*    **TTL** - The Time To Live (TTL) of an item is the amount of time between
+when that item is stored and it is considered stale. The TTL is normally defined
+by an integer representing time in seconds.
+
+*    **Expiration** - The actual time when an item is set to go stale. This it
+typically calculated by adding the TTL to the time when an object is stored.
+
+    An item with a 300 second TTL stored at 1:30:00 will have an expiration at
+    1:35:00.
+
+*    **Key** - A string that uniquely identifies the cached item. Implementing
+Libraries are responsible for any encoding or escaping required by their
+backends, but must be able to supply the original key if needed. Keys should not
+contain the special characters listed:
+
+### 1.2 CacheItem
+
+By `CacheItem` we refer to a object that implements the
+`Psr\Cache\CacheItemInterface` interface.
+
+By using the cache item implementations will guarantee consistency across
+various systems and ensure that the user will always retrieve the expected data
+without performing any additional operations.
+
+### 1.3 Cache
+
+By `Cache` we refer to a object that implements the `Psr\Cache\CacheInterface`
+interface.
+
+If the user does not provide a TTL value then the `Cache` MUST set a default
+value that is either configured by the user or, if not available, the maximum
+value allowed by cache system. If the cache system does not support a TTL
+option then the user specified or the default TTL values will be ignored.
+
+It will be the implementation job to define what values are considered valid
+or invalid for key names but the user MUST be aware of the accepted values
+by the underlying solution both for TTL values as well as for key names.
+
+
+### CacheItem ###
+The CacheItem objects are generated by the Cache class. CacheItem objects encapsulate the key and value of the stored cache entry
+
+``` php
+<?php
+namespace Psr\Cache;
+
+interface CacheItemInterface
+{
+
+    /**
+     * Get the key associated with this CacheItem
+     * 
+     * @return string
+     */
+    public function getKey();
+
+    /**
+     * Obtain the value of this cache item
+     * 
+     * @return mixed
+     */
+    public function getValue();
+
+    /**
+     * This boolean value tells us if our cache item is currently in the cache or not
+     * 
+     * @return boolean
+     */
+    public function isHit();
+
+    /**
+     * @param mixed $value
+     */
+    public function setValue($value);
+
+}
+```
+
+
+``` php
+namespace Psr\Cache;
+
+use Psr\CacheItemInterface;
+
+interface CacheInterface
+{
+
+    /**
+     * Remove an item from the cache by its unique key
+     * 
+     * @param string $key The unique cache key of the item to remove
+     * @return boolean    The result of the delete operation
+     */
+    public function remove($key);
+
+    /**
+     * This will wipe out the entire cache's keys
+     * 
+     * @return boolean The result of the empty operation
+     */
+    public function empty();
+
+    /**
+     * Persisting our data in the cache, uniquely referenced by a key with an optional expiration TTL time.
+     * 
+     * @param string       $key The key of the item to store
+     * @param mixed        $val The value of the item to store
+     * @param null|integer $ttl Optional. The TTL value of this item as a timestamp for when it will expire if 
+     *                          the implementing library choose to use this value
+     * @return boolean
+     */
+    public function set($key, $val, $ttl = null);
+
+    /**
+     * Here we pass in a cache key to be fetched from the cache. 
+     * A CacheItem object will be constructed and returned to us
+     * 
+     * @param string $key The unique key of this item in the cache
+     * @return CacheItem  The newly populated CacheItem class representing the stored data in the cache
+     */
+    public function getItem($key);
+
+    /**
+     * This method can be used for re-persistence of an existing cache item after being retrieved from Cache->
+     * It's good if you have an existing CacheItem and just want to change its value then you can stick it back in the cache
+     * If the TTL is not null then the TTL value for the Item will be overwritten either by this new TTL value
+     * 
+     * @param CacheItem     $item   The CacheItem object being passed for persistence in the cache
+     * @param null|integer  $ttl    Optional. If there is an expiration time for this object then this parameter is used.
+     * @return boolean              The result of the set operation
+     */
+    public function setItem(CacheItemInterface $item, $ttl = null);
+
+    /**
+     * Remove multiple cache items in a single operation
+     * 
+     * @param array  $keys The array of keys to be removed
+     * @return array An array of 'key' => result, elements. Each array row has the key being deleted 
+     *               and the result of that operation. The result will be a boolean of true or false 
+     *               representing if the cache item was removed or not
+     */
+    public function removeItems($keys);
+
+    /**
+     * Obtain multiple CacheItems by their unique keys
+     * 
+     * @param array $keys A list of keys that can obtained in a single operation.
+     * @return array      An array of CacheItem classes. 
+     *                    The resulting array must use the CacheItem's key as the associative key for the array.
+     */
+    public function getItems($keys);
+
+    /**
+     * Persistence or re-persistence of multiple CacheItem objects, 
+     * this does not differ from the setItem() method except that it's setting multiple items at once
+     * If the TTL is not null then the TTL value for the Item will be overwritten either by this new TTL value
+     * 
+     * @param array         $items An array of CacheItem objects, this is for a multiple-set operation.
+     * @param null|integer  $ttl   Optional. If the implementing library has expiration support then the TTL timestamp value is passed in here. 
+     * @return boolean The result of the multiple-set operation
+     */
+    public function setItems($items, $ttl = null);
+
+}
+```