From b639c5ce87e245fd4bc34278b1bceb6a9bf95b67 Mon Sep 17 00:00:00 2001 From: Timothy J Warren Date: Tue, 6 Sep 2016 20:57:24 -0400 Subject: [PATCH] Add some documentation to the README --- README.md | 68 +++++++++++++++++++++++++++++++++- src/Driver/AbstractDriver.php | 9 +++-- src/Driver/MemcacheDriver.php | 3 +- src/Driver/MemcachedDriver.php | 10 ++++- src/Driver/NullDriver.php | 11 +++--- src/Driver/RedisDriver.php | 5 ++- src/Pool.php | 21 +++++++---- 7 files changed, 104 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 0db316c..51164cd 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,69 @@ # Banker -A Caching library implementing the PSR-6 interface for several common cache backends \ No newline at end of file +A Caching library implementing the PSR-6 interface for several common cache +backends + +## Cache Backends +* Memcache +* Memcached +* Redis +* Null - no persistence + +### Basic Usage +```php +// Create the pool +$pool = new Aviat\Banker\Pool($config, $logger); + +// Grab an item from the cache +$item = $pool->getItem('foo'); + +// Was there a cache hit? +if ( ! $item->isHit()) +{ + // ... Generation of value to cache + $item->set($value); + $item->save(); +} +else +{ + $value = $item->get(); +} +``` + +#### Configuration / Connection array + +The config array passed to the Pool class constructor determines +which server to connect to. Regardless of the backend, the basic +structure is like so: + +```php +[ + 'driver' => 'null', // null, redis, memcache, memcached + 'connection' => [ + // driver setup, see below for the structure for each + // driver + ], + 'options' => [ + // Optional: + // Set additional driver-specific options, like persistence for + // Memcached, or a prefix for Redis keys + ] +] +``` + +Below are the connection arrays for each backend: + +Memcache / Memcached: +```php +[ + 'host' => 'localhost', // hostname or socket + 'port' => 11211, // Port needs to be 0 if socket + 'persistent' => false, // Use persistent connection +] +``` + +Redis: +See [Predis](https://github.com/nrk/predis#connecting-to-redis) documentation. An empty array will connect to localhost on port 6379. + +Null: +No connection parameters \ No newline at end of file diff --git a/src/Driver/AbstractDriver.php b/src/Driver/AbstractDriver.php index 582d9d1..4183e7c 100644 --- a/src/Driver/AbstractDriver.php +++ b/src/Driver/AbstractDriver.php @@ -22,7 +22,7 @@ use Psr\Log\LoggerAwareInterface; * Base class for cache backends */ abstract class AbstractDriver implements DriverInterface, LoggerAwareInterface { - + use \Aviat\Banker\LoggerTrait; /** @@ -31,7 +31,7 @@ abstract class AbstractDriver implements DriverInterface, LoggerAwareInterface { * @var mixed */ protected $conn; - + /** * Data to be stored later * @@ -43,9 +43,10 @@ abstract class AbstractDriver implements DriverInterface, LoggerAwareInterface { * Common constructor interface for driver classes * * @param array $config - Connection parameters for the specified backend + * @param array $options - Special connection options for the specified backend */ - abstract public function __construct(array $config = []); - + abstract public function __construct(array $config = [], array $options = []); + /** * Common destructor */ diff --git a/src/Driver/MemcacheDriver.php b/src/Driver/MemcacheDriver.php index 1761574..e4a4c19 100644 --- a/src/Driver/MemcacheDriver.php +++ b/src/Driver/MemcacheDriver.php @@ -27,9 +27,10 @@ class MemcacheDriver extends AbstractDriver { * Driver for PHP Memcache extension * * @param array $config + * @param array $options * @throws CacheException */ - public function __construct(array $config = []) + public function __construct(array $config = [], array $options = []) { // @codeCoverageIgnoreStart if ( ! class_exists('Memcache')) diff --git a/src/Driver/MemcachedDriver.php b/src/Driver/MemcachedDriver.php index 2b61494..57ca798 100644 --- a/src/Driver/MemcachedDriver.php +++ b/src/Driver/MemcachedDriver.php @@ -30,9 +30,10 @@ class MemcachedDriver extends AbstractDriver { * Driver for PHP Memcache extension * * @param array $config + * @param array $options * @throws CacheException */ - public function __construct(array $config = []) + public function __construct(array $config = [], array $options = []) { // @codeCoverageIgnoreStart if ( ! class_exists('Memcached')) @@ -46,8 +47,13 @@ class MemcachedDriver extends AbstractDriver { $this->conn = new Memcached(); $this->conn->setOption(Memcached::OPT_BINARY_PROTOCOL, true); $this->conn->addServer($config['host'], $config['port']); + + // @codeCoverageIgnoreStart + if ( ! empty($options)) + { + $this->conn->setOptions($options); + } } - // @codeCoverageIgnoreStart catch (MemcachedException $e) { // Rewrite MemcachedException as a CacheException to diff --git a/src/Driver/NullDriver.php b/src/Driver/NullDriver.php index 12902d9..1079365 100644 --- a/src/Driver/NullDriver.php +++ b/src/Driver/NullDriver.php @@ -34,12 +34,13 @@ class NullDriver extends AbstractDriver { * NullDriver constructor. * * @param array $config + * @param array $options */ - public function __construct(array $config = []) + public function __construct(array $config = [], array $options = []) { $this->store = []; } - + /** * Clean up nothing */ @@ -67,8 +68,8 @@ class NullDriver extends AbstractDriver { */ public function get($key) { - return ($this->exists($key)) - ? $this->store[$key] + return ($this->exists($key)) + ? $this->store[$key] : NULL; } @@ -144,7 +145,7 @@ class NullDriver extends AbstractDriver { $this->store = []; return TRUE; } - + /** * Set the specified key to expire at the given time * diff --git a/src/Driver/RedisDriver.php b/src/Driver/RedisDriver.php index bea2baf..1503be6 100644 --- a/src/Driver/RedisDriver.php +++ b/src/Driver/RedisDriver.php @@ -35,9 +35,10 @@ class RedisDriver extends AbstractDriver { * RedisDriver constructor. * * @param array $config + * @param array $options - Predis library connection options * @throws CacheException */ - public function __construct(array $config = []) + public function __construct(array $config = [], array $options = []) { // @codeCoverageIgnoreStart if ( ! class_exists('Predis\\Client')) @@ -46,7 +47,7 @@ class RedisDriver extends AbstractDriver { } // @codeCoverageIgnoreEnd - $this->conn = new Client($config); + $this->conn = new Client($config, $options); } /** diff --git a/src/Pool.php b/src/Pool.php index 94419ae..be0b36a 100644 --- a/src/Pool.php +++ b/src/Pool.php @@ -30,7 +30,7 @@ use Aviat\Banker\ItemCollection; * The main cache manager */ class Pool implements CacheItemPoolInterface, LoggerAwareInterface { - + use LoggerTrait; /** @@ -55,7 +55,7 @@ class Pool implements CacheItemPoolInterface, LoggerAwareInterface { public function __construct(array $config, LoggerInterface $logger = NULL) { $this->driver = $this->loadDriver($config); - + if ( ! is_null($logger)) { $this->setLogger($logger); @@ -84,7 +84,7 @@ class Pool implements CacheItemPoolInterface, LoggerAwareInterface { { throw new InvalidArgumentException(); } - + // If a deferred item exists, return that if (array_key_exists($key, $this->deferred)) { @@ -117,7 +117,7 @@ class Pool implements CacheItemPoolInterface, LoggerAwareInterface { { return new ItemCollection([]); } - + foreach($keys as $key) { if ( ! is_string($key)) @@ -125,7 +125,7 @@ class Pool implements CacheItemPoolInterface, LoggerAwareInterface { throw new InvalidArgumentException(); } } - + // Get the set of items selected $items = []; $rawItems = $this->driver->getMultiple($keys); @@ -167,7 +167,7 @@ class Pool implements CacheItemPoolInterface, LoggerAwareInterface { { throw new InvalidArgumentException(); } - + // See if there are any deferred items if (array_key_exists($key, $this->deferred)) { @@ -292,7 +292,7 @@ class Pool implements CacheItemPoolInterface, LoggerAwareInterface { { $result = $result && $this->save($item); } - + if ($result === TRUE) { $this->deferred = []; @@ -312,6 +312,11 @@ class Pool implements CacheItemPoolInterface, LoggerAwareInterface { $driver = ucfirst(strtolower($driverConfig['driver'])); $class = __NAMESPACE__ . "\\Driver\\${driver}Driver"; - return new $class($driverConfig['connection']); + if ( ! array_key_exists('options', $driverConfig)) + { + $driverConfig['options'] = []; + } + + return new $class($driverConfig['connection'], $driverConfig['options']); } } \ No newline at end of file