Update documentation to reflect Stash v0.14.0

API.rst

@@ -11,35 +11,44 @@ The Pool class represents the entire caching system and all of the items in it.
 retrieve Items from the cache, as well as to perform bulk operations on the system such as Purging or Clearing the
 cache.
 
+clear
+-----
 
-setDriver
----------
+*clear()*
 
-*setDriver($driver)*
+The clear function completely empties all items associated with the Pool. After calling this every Item will be considered a miss and will have to be regenerated.
 
-Sets the driver for use by the caching system. This driver handles the direct interface with the caching backends,
-keeping the system specific development abstracted out.
 
+__construct
+------------
 
-setLogger
----------
+*__construct(DriverInterface $driver = null)*
 
-*setLogger($logger)*
+The constructor takes a Driver class which is used for persistent storage. If no driver is provided then the Ephemeral driver is used by default.
 
-Sets a PSR LoggerInterface style logging client to enable the tracking of errors.
 
+commit
+------
 
-setNamespace
-------------
+*commit()*
 
-Places the Pool inside of a "namespace". All Items inside a specific namespace should be completely segmented from all
-other Items.
+The commit function persists any Item that was put into the Pool using the savedDeferred function and hasn't been saved yet.
 
 
-getNamespace
-------------
+deleteItems
+-----------
+
+*deleteItems(array $keys)*
+
+Removes items from the Pool based off of their keys.
 
-Retrieves the current namespace, or false if one isn't set.
+
+getDriver
+---------
+
+*getDriver()*
+
+Returns the underlying driver used by the Pool to persist data.
 
 
 getItem
@@ -51,21 +60,30 @@ The getItem function takes in a key and returns an associated Item object. The s
 :ref:`basics` page.
 
 
-getItemIterator
----------------
+getItems
+--------
 
-*getItemIterator(array $keys)*
+*getItems(array $keys)*
 
-The getItemIterator function takes in an array of keys and returns an Iterator object populated by Item objects for
+The getItems function takes in an array of keys and returns an Iterator object populated by Item objects for
 those keys. The structure of keys can be found on the :ref:`basics` page.
 
 
-flush
------
+getNamespace
+------------
+
+*getNamespace()*
+
+Retrieves the current namespace, or false if one isn't set.
+
+
+hasItem
+-------
 
-*flush()*
+*hasItem($key)*
 
-The flush function completely empties all items associated with the Pool. After calling this every Item will be considered a miss and will have to be regenerated.
+Returns true if the specified key has a value stored in the Pool. A safer way to do this would be to use the isHit/isMiss
+functions in the Item class.
 
 
 purge
@@ -80,66 +98,59 @@ It's important that this function is not called from inside a normal request, as
 occasionally take some time.
 
 
+save
+----
 
-Item
-=====
+*save($item)*
 
-The Item class represents specific pieces of data in the caching system. Item
-objects are created by the Pool class.
+Takes an Item class and persists it to the Pool.
 
 
-get
-----
+saveDeferred
+------------
 
-*get($invalidation == Invalidation::PRECOMPUTE, [$args])*
+*saveDeferred($item)*
 
-Retrieves the stored value of the Item or null if one is not set. Because null can be a valid stored object it is
-important to call *isMiss* in order to actually check it's validity.
+Takes an Item class and eventually persists it to the Pool. This allows Stash to buffer cache operations and send them together,
+optimizing the number of cache calls.
 
 
-The get function can take a series of optional arguments defining how it handles cache misses. The first of these
-options is the invalidation method to be used, while the other options all provide invalidation specific options. The
-:ref:`invalidation` page contains much more information about hos to use this functionality.
+setDriver
+---------
 
+*setDriver($driver)*
 
-isMiss
-------
+Sets the driver for use by the caching system. This driver handles the direct interface with the caching backends,
+keeping the system specific development abstracted out.
 
-*isMiss()*
 
-The isMiss function returns true when the current Item has either stale or no data. Since Stash is capable of storing
-both null and false values and returning them via the get function this is the only real way to test whether a cached
-value is usable or not.
+setItemClass
+------------
 
-The exact behavior used to define a cache miss is defined by the invalidation method used for the object. The
-:ref:`invalidation` page contains much more information about hos to use this functionality.
 
+setLogger
+---------
 
-lock
-----
+*setLogger($logger)*
 
-*lock($ttl = null)*
+Sets a PSR LoggerInterface style logging client to enable the tracking of errors.
 
-This should be called right before the script attempts to regenerate data from a cache miss. It signifies to other
-processes or requests that the data is being generated and allows them to take special action to improve system
-performance. Put more simply, just call this function and your cache will be higher performing as a result.
 
-The exact effect of this function depends on which invalidation method is being used. The :ref:`invalidation` page
-contains much more information about how to use this functionality.
+setNamespace
+------------
 
+*setNamespace($namespace)*
 
-set
-----
+Places the Pool inside of a "namespace". All Items inside a specific namespace should be completely segmented from all
+other Items.
 
-*set($data, $ttl = null)*
 
-The set function is used to populate the cache with data. The first argument can be any type of data that is able to be
-serialized- essentially everything except resources and classes which can't be serialized.
 
-The second argument defines how long the Item will be stored in the cache. This is a maximum time, as Items can be
-cleared or removed earlier but will never be considered a cache hit after it. This argument can either be a DateTime
-defining a specific expiration or an integer representing the time, in seconds, that the data should be considered
-fresh.
+Item
+=====
+
+The Item class represents specific pieces of data in the caching system. Item
+objects are created by the Pool class.
 
 
 clear
@@ -153,6 +164,30 @@ If hierarchical or "stackable" caching is being used this function will also rem
 the :ref:`basics` document goes into more detail about how that works.
 
 
+disable
+-------
+
+*disable()*
+
+The disable function prevents any read or write operations and forces all the other calls to fail gracefully.
+
+
+expiresAfter
+------------
+
+*expiresAfter(int|\DateInterval $time)*
+
+Sets the expiration based off of an integer or DateInterval.
+
+
+expiresAt
+---------
+
+*expiresAt(\DateTimeInterface $expiration)*
+
+Sets the expiration to a specific time.
+
+
 extend
 ------
 
@@ -162,13 +197,13 @@ This extends the Item's lifetime without changing it's data. Like the set functi
 integer.
 
 
-getKey
-------
+get
+---
 
-*getKey()*
+*get($invalidation)*
 
-The getKey function returns this Item's key as a string. This is particularly useful when the Item is returned as a
-group of Items in an Iterator.
+Retrieves the stored value of the Item or null if one is not set. Because null can be a valid stored object it is
+important to call *isMiss* in order to actually check it's validity.
 
 
 getCreation
@@ -187,12 +222,98 @@ getExpiration
 This returns a DateTime of the Item's expiration time, if it is available.
 
 
-disable
--------
+getKey
+------
+
+*getKey()*
+
+The getKey function returns this Item's key as a string. This is particularly useful when the Item is returned as a
+group of Items in an Iterator.
+
+
+isDisabled
+----------
+
+*isDisabled()*
+
+Returns true if Stash has been disabled (typically via the disable function).
+
+
+isHit
+-----
+
+*isHit()*
+
+The isHit function returns false when the current Item has either stale or no data. Since Stash is capable of storing
+both null and false values and returning them via the get function this is the only real way to test whether a cached
+value is usable or not.
+
+The exact behavior used to define a cache miss is defined by the invalidation method used for the object. The
+:ref:`invalidation` page contains much more information about hos to use this functionality.
+
+
+
+isMiss
+------
+
+*isMiss()*
+
+This function is the opposite of isHit. Is is here for backwards compatibility, but to be PSR-6 compliant use the
+isHit function instead.
+
+
+lock
+----
+
+*lock($ttl = null)*
+
+This should be called right before the script attempts to regenerate data from a cache miss. It signifies to other
+processes or requests that the data is being generated and allows them to take special action to improve system
+performance. Put more simply, just call this function and your cache will be higher performing as a result.
+
+The exact effect of this function depends on which invalidation method is being used. The :ref:`invalidation` page
+contains much more information about how to use this functionality.
+
+
+save
+----
+
+
+set
+---
+
+*set($data)*
+
+The set function is used to populate the cache with data. The only argument can be any type of data that is able to be
+serialized- essentially everything except resources and classes which can't be serialized.
+
+
+
+setInvalidationMethod
+---------------------
+
+*setInvalidationMethod($invalidation == Invalidation::PRECOMPUTE, [$args])*
+
+This function can take a series of optional arguments defining how it handles cache misses. The first of these
+options is the invalidation method to be used, while the other options all provide invalidation specific options. The
+:ref:`invalidation` page contains much more information about hos to use this functionality.
+
+
+setLogger
+---------
+
+
+setTTL
+------
+
+*setTTL($ttl = null)*
+
+The second argument defines how long the Item will be stored in the cache. This is a maximum time, as Items can be
+cleared or removed earlier but will never be considered a cache hit after it. This argument can either be a DateTime
+defining a specific expiration or an integer representing the time, in seconds, that the data should be considered
+fresh.
 
-*disable()*
 
-The disable function prevents any read or write operations and forces all the other calls to fail gracefully.
 
 
 

AddingDrivers.rst

@@ -11,7 +11,7 @@ appreciated, so please feel free to issue a pull request to get it included in t
 Keys
 ====
 
-Stash provides a variety of methods for developers to define keys, but it normalizes those keys into an array before
+Stash asks for keys to be provided as strings, but it normalizes those keys into an array before
 passing it to the driver. For the purposes of driver development a key is always an indexed array.
 
 For example, where a user can represent a key as "path/to/data", it will always come to the Driver as