Provide a PSR-16 decorator for zend-cache storage adapters

CHANGELOG.md

@@ -6,37 +6,48 @@ All notable changes to this project will be documented in this file, in reverse
 
 ### Added
 
+- [#148](https://github.com/zendframework/zend-cache/pull/148) adds support for PHP 7.1 and 7.2.
+
+- [#152](https://github.com/zendframework/zend-cache/pull/152) adds an adapter providing [PSR-16](https://www.php-fig.org/psr/psr-16/) (Caching Library Interface) support.
+  The new class, `Zend\Cache\Psr\SimpleCacheDecorator`, accepts a
+  `Zend\Cache\Storage\StorageInterface` instance to its constructor, and proxies
+  the various PSR-16 methods to it.
+
+- [#46](https://github.com/zendframework/zend-cache/issues/46) adds support for [PSR-6](https://www.php-fig.org/psr/psr-6/) (Caching Interface).
+  It provides an implementation of `Psr\Cache\CacheItemPoolInterface` via
+  `Zend\Cache\Psr\CacheItemPoolAdapter`, which accepts a
+  `Zend\Cache\Storage\StorageInterface` instance to its constructor, and proxies
+  the various PSR-6 methods to it. It also provides a
+  `Psr\Cache\CacheItemInterface` implementation via `Zend\Cache\Psr\CacheItem`,
+  which provides a value object for both introspecting cache fetch results, as
+  well as providing values to cache.
+
 - [#154](https://github.com/zendframework/zend-cache/pull/154) adds an ext-mongodb adapter, `Zend\Cache\Storage\Adapter\ExtMongoDb`.
   You may use the `StorageFactory` to create an instance using either the fully qualified class
   name as the adapter name, or the strings `ext_mongo_db` or `ExtMongoDB` (or most variations
   on case of the latter string). The options it accepts are the same as for the existing
   `Zend\Cache\Storage\Adapter\MongoDb`, and it provides the same capabilities. The adapter
   requires the mongodb/mongodb package to operate.
 
-- [#148](https://github.com/zendframework/zend-cache/pull/148) adds support for PHP 7.1 and 7.2.
-
 - [#120](https://github.com/zendframework/zend-cache/pull/120) adds the ability to configure alternate file suffixes for both
   cache and tag cache files within the Filesystem adapter. Use the `suffix` and `tag_suffix`
   options to set them; they will default to `dat` and `tag`, respectively.
 
-- [#116](https://github.com/zendframework/zend-cache/pull/116)
-  docblock method chaining consistency
-- [#46](https://github.com/zendframework/zend-cache/issues/46)
-  Add wrapper for PSR-6
 - [#79](https://github.com/zendframework/zend-cache/issues/79)
   Add capability for the "lock-on-expire" feature (úsed by Zend Data Cache)
 
 ### Changed
 
-- Nothing.
+- [#116](https://github.com/zendframework/zend-cache/pull/116) adds docblock method chaining consistency.
 
 ### Deprecated
 
-- [#101](https://github.com/zendframework/zend-cache/pull/101)
-  bump minimum php version to 5.6, as 5.5 goes EOL
+- Nothing.
 
 ### Removed
 
+- [#101](https://github.com/zendframework/zend-cache/pull/101) removes support for PHP 5.5.
+
 - [#148](https://github.com/zendframework/zend-cache/pull/148) removes support for HHVM.
 
 ### Fixed
@@ -49,8 +60,7 @@ All notable changes to this project will be documented in this file, in reverse
 
 - [#150](https://github.com/zendframework/zend-cache/pull/150) fixes an issue with how CAS tokens are handled when using the memcached adapter.
 
-- [#61](https://github.com/zendframework/zend-cache/pull/61)
-  Zend Data Cache: minTtl => 1
+- [#61](https://github.com/zendframework/zend-cache/pull/61) sets the Zend Data Cache minTtl value to 1.
 
 ## 2.7.3 - TBD
 

composer.json

@@ -18,6 +18,7 @@
     "require": {
         "php": "^5.6 || ^7.0",
         "psr/cache": "^1.0",
+        "psr/simple-cache": "^1.0",
         "zendframework/zend-eventmanager": "^2.6.3 || ^3.2",
         "zendframework/zend-servicemanager": "^2.7.8 || ^3.3",
         "zendframework/zend-stdlib": "^2.7.7 || ^3.1"
@@ -66,6 +67,10 @@
     "config": {
         "sort-packages": true
     },
+    "provide": {
+        "psr/cache-implementation": "1.0",
+        "psr/simple-cache-implementation": "1.0"
+    },
     "extra": {
         "branch-alias": {
             "dev-master": "2.7.x-dev",

docs/book/psr16.md

@@ -0,0 +1,66 @@
+# PSR-16 Support
+
+- Since 2.8.0
+
+[PSR-16](https://www.php-fig.org/psr/psr-16/) provides a simplified approach to
+cache access that does not involve cache pools, tags, deferment, etc.; it
+can be thought of as a key/value storage approach to caching.
+
+zend-cache provides PSR-16 support via the class
+`Zend\Cache\Psr\SimpleCacheDecorator`. This class implements PSR-16's
+`Psr\SimpleCache\CacheInterface`, and composes a
+`Zend\Cache\Storage\StorageInterface` instance to which it proxies all
+operations.
+
+Instantiation is as follows:
+
+```php
+use Zend\Cache\StorageFactory;
+use Zend\Cache\Psr\SimpleCacheDecorator;
+
+$storage = StorageFactory::factory([
+    'adapter' => [
+        'name'    => 'apc',
+        'options' => [],
+    ],
+]);
+
+$cache = new SimpleCacheDecorator($storage);
+```
+
+Once you have a `SimpleCacheDecorator` instance, you can perform operations per
+that specification:
+
+```php
+// Use has() to determine whether to fetch the value or calculate it:
+$value = $cache->has('someKey') ? $cache->get('someKey') : calculateValue();
+if (! $cache->has('someKey')) {
+    $cache->set('someKey', $value);
+}
+
+// Or use a default value:
+$value = $cache->get('someKey', $defaultValue);
+```
+
+When setting values, whether single values or multiple, you can also optionally
+provide a Time To Live (TTL) value. This proxies to the underlying storage
+instance's options, temporarily resetting its TTL value for the duration of the
+operation. TTL values may be expressed as integers (in which case they represent
+seconds) or `DateInterval` instances. As examples:
+
+```php
+$cache->set('someKey', $value, 30); // set TTL to 30s
+$cache->set('someKey', $value, new DateInterval('P1D'); // set TTL to 1 day
+
+$cache->setMultiple([
+    'key1' => $value1,
+    'key2' => $value2,
+], 3600); // set TTL to 1 hour
+$cache->setMultiple([
+    'key1' => $value1,
+    'key2' => $value2,
+], new DateInterval('P6H'); // set TTL to 6 hours
+```
+
+For more details on what methods are exposed, consult the [CacheInterface
+specification](https://www.php-fig.org/psr/psr-16/#21-cacheinterface).

docs/book/psr6.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-The `Zend\Cache\Psr\CacheItemPoolAdapter` provides a [PSR-6](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-6-cache.md)
+The `Zend\Cache\Psr\CacheItemPoolAdapter` provides a [PSR-6](https://www.php-fig.org/psr/psr-6/)
 compliant wrapper for supported storage adapters.
 
 PSR-6 specifies a common interface to cache storage, enabling developers to switch between implementations without

mkdocs.yml

@@ -14,6 +14,7 @@ pages:
         - OutputCache: pattern/output-cache.md
         - CaptureCache: pattern/capture-cache.md
     - PSR-6: psr6.md
+    - PSR-16: psr16.md
 site_name: zend-cache
 site_description: Zend\Cache
 repo_url: 'https://github.com/zendframework/zend-cache'

src/Psr/CacheItemPoolAdapter.php

@@ -23,6 +23,8 @@
  */
 class CacheItemPoolAdapter implements CacheItemPoolInterface
 {
+    use SerializationTrait;
+
     /**
      * @var StorageInterface
      */
@@ -33,16 +35,6 @@ class CacheItemPoolAdapter implements CacheItemPoolInterface
      */
     private $deferred = [];
 
-    /**
-     * @var bool
-     */
-    private $serializeValues = false;
-
-    /**
-     * @var string
-     */
-    private static $serializedFalse;
-
     /**
      * Constructor.
      *
@@ -57,12 +49,7 @@ class CacheItemPoolAdapter implements CacheItemPoolInterface
     public function __construct(StorageInterface $storage)
     {
         $this->validateStorage($storage);
-
-        $this->serializeValues = $this->shouldSerialize($storage);
-        if ($this->serializeValues) {
-            static::$serializedFalse = serialize(false);
-        }
-
+        $this->memoizeSerializationCapabilities($storage);
         $this->storage = $storage;
     }
 
@@ -350,27 +337,6 @@ private function validateStorage(StorageInterface $storage)
         }
     }
 
-    /**
-     * Returns true if capabilities indicate values should be serialized before saving to preserve data types
-     * @param StorageInterface $storage
-     * @return bool
-     */
-    private function shouldSerialize(StorageInterface $storage)
-    {
-        $capabilities = $storage->getCapabilities();
-        $requiredTypes = ['string', 'integer', 'double', 'boolean', 'NULL', 'array', 'object'];
-        $types = $capabilities->getSupportedDatatypes();
-        foreach ($requiredTypes as $type) {
-            // 'object' => 'object' is OK
-            // 'integer' => 'string' is not (redis)
-            // 'integer' => 'integer' is not (memcache)
-            if (! (isset($types[$type]) && in_array($types[$type], [true, 'array', 'object'], true))) {
-                return true;
-            }
-        }
-        return false;
-    }
-
     /**
      * Unserializes value, marking isHit false if it fails
      * @param $value

src/Psr/SerializationTrait.php

@@ -0,0 +1,69 @@
+<?php
+/**
+ * @see       https://github.com/zendframework/zend-cache for the canonical source repository
+ * @copyright Copyright (c) 2018 Zend Technologies USA Inc. (https://www.zend.com)
+ * @license   https://github.com/zendframework/zend-cache/blob/master/LICENSE.md New BSD License
+ */
+
+namespace Zend\Cache\Psr;
+
+use Zend\Cache\Storage\StorageInterface;
+
+/**
+ * Provides common functionality surrounding value de/serialization as required
+ * by both PSR-6 and PSR-16
+ */
+trait SerializationTrait
+{
+    /**
+     * @var bool
+     */
+    private $serializeValues = false;
+
+    /**
+     * @var string
+     */
+    private static $serializedFalse;
+
+    /**
+     * Determine if the given storage adapter requires serialization.
+     *
+     * Determines if the given storage adapter requires serialization. If so,
+     * set $serializeValues to true, and serialize a boolean false for later
+     * comparisons.
+     *
+     * @param StorageInterface $storage
+     * @return void
+     */
+    private function memoizeSerializationCapabilities(StorageInterface $storage)
+    {
+        $capabilities = $storage->getCapabilities();
+        $requiredTypes = ['string', 'integer', 'double', 'boolean', 'NULL', 'array', 'object'];
+        $types = $capabilities->getSupportedDatatypes();
+        $shouldSerialize = false;
+
+        foreach ($requiredTypes as $type) {
+            // 'object' => 'object' is OK
+            // 'integer' => 'string' is not (redis)
+            // 'integer' => 'integer' is not (memcache)
+            if (! (isset($types[$type]) && in_array($types[$type], [true, 'array', 'object'], true))) {
+                $shouldSerialize = true;
+                break;
+            }
+        }
+
+        if ($shouldSerialize) {
+            static::$serializedFalse = serialize(false);
+        }
+
+        $this->serializeValues = $shouldSerialize;
+    }
+
+    /**
+     * Unserialize a value retrieved from the cache.
+     *
+     * @param string $value
+     * @return mixed
+     */
+    abstract public function unserialize($value);
+}