qa: deprecate storage option for PatternOptions

Since v2.10, the storage adapter have their own package. In v3.0 these, adapters have to register themselves to the `AdapterPluginManager` when the plugin manager is being instantiated and thus, this component wont be aware of which adapters are available without using a `PSR-11` container. This commit aims to provide a proper dependency injection layer to all cache patterns while deprecating the old `storage` option for `PatternOptions`. Signed-off-by: Maximilian Bösing <2189546+boesing@users.noreply.github.com>
laminas · May 2, 2021 · 680478b · 680478b
1 parent 3b77bbe
commit 680478b
Show file tree

Hide file tree

Showing 32 changed files with 853 additions and 345 deletions.
diff --git a/docs/book/pattern/callback-cache.md b/docs/book/pattern/callback-cache.md
@@ -5,42 +5,40 @@ The callback cache pattern caches the results of arbitrary PHP callables.
 ## Quick Start
 
 ```php
-use Laminas\Cache\PatternFactory;
+use Laminas\Cache\Pattern\CallbackCache;
 use Laminas\Cache\Pattern\PatternOptions;
+use Laminas\Cache\Storage\StorageInterface;
 
-// Via the factory:
-$callbackCache = PatternFactory::factory('callback', [
-    'storage'      => 'apc',
-    'cache_output' => true,
-]);
+/** @var StorageInterface $storage */
+$storage = null; // Can be any instance of StorageInterface
 
 // Or the equivalent manual instantiation:
-$callbackCache = new \Laminas\Cache\Pattern\CallbackCache();
-$callbackCache->setOptions(new PatternOptions([
-    'storage'      => 'apc',
-    'cache_output' => true,
-]));
+$callbackCache = new CallbackCache(
+    $storage,
+    new PatternOptions([
+        'cache_output' => true,
+    ])
+);
 ```
 
 ## Configuration Options
 
 Option | Data Type | Default Value | Description
 ------ | --------- | ------------- | -----------
-`storage` | `string | array | Laminas\Cache\Storage\StorageInterface` | none | Adapter used for reading and writing cached data.
-`cache_output` | `boolean` | `true` | Whether or not to cache callback output.
+`storage` | `string | array | Laminas\Cache\Storage\StorageInterface` | none | **deprecated** Adapter used for reading and writing cached data.
+`cache_output` | `bool` | `true` | Whether or not to cache callback output.
 
 ## Available Methods
 
-In addition to the methods defined in the `PatternInterface`, this
+In addition to the methods defined in the `PatternInterface` and the `StorageCapableInterface`, this
 implementation provides the following methods.
 
 ```php
 namespace Laminas\Cache\Pattern;
 
 use Laminas\Cache\Exception;
-use Laminas\Stdlib\ErrorHandler;
 
-class CallbackCache extends AbstractPattern
+class CallbackCache extends AbstractStorageCapablePattern
 {
     /**
      * Call the specified callback or get the result from cache

diff --git a/docs/book/pattern/capture-cache.md b/docs/book/pattern/capture-cache.md
@@ -20,10 +20,14 @@ ErrorDocument 404 /index.php
 And add the cache to the related application script, e.g. `index.php`:
 
 ```php
-use Laminas\Cache\PatternFactory;
-$capture = Laminas\Cache\PatternFactory::factory('capture', [
-    'public_dir' => __DIR__,
-]);
+use Laminas\Cache\Pattern\CaptureCache;
+use Laminas\Cache\Pattern\PatternOptions;
+
+$capture = new CaptureCache(
+    new PatternOptions([
+        'public_dir' => __DIR__,
+    ])
+);
 
 // Start capturing all output, excluding headers, and write to the public
 // directory:
@@ -44,7 +48,7 @@ Option | Data Type | Default Value | Description
 `file_locking` | `bool` | `true` | Whether or not to lock output files when writing.
 `file_permission` | `int | bool` | `0600` (`false` on Windows) | Default permissions for generated output files.
 `dir_permission` | `int | bool` | `0700` (`false` on Windows) | Default permissions for generated output directories.
-`umask` | `int` | `bool` | `false` | Whether or not to umask generated output files / directories.
+`umask` | `int | false` | `false` | Whether or not to umask generated output files / directories.
 
 ## Available Methods
 
@@ -55,7 +59,6 @@ exposes the following methods.
 namespace Laminas\Cache\Pattern;
 
 use Laminas\Cache\Exception;
-use Laminas\Stdlib\ErrorHandler;
 
 class CaptureCache extends AbstractPattern
 {
@@ -138,9 +141,14 @@ Use the following script:
 
 ```php
 // index.php
-$captureCache = Laminas\Cache\PatternFactory::factory('capture', [
-    'public_dir' => __DIR__,
-]);
+use Laminas\Cache\Pattern\CaptureCache;
+use Laminas\Cache\Pattern\PatternOptions;
+
+$capture = new CaptureCache(
+    new PatternOptions([
+        'public_dir' => __DIR__,
+    ])
+);
 
 // TODO
 ```
diff --git a/docs/book/pattern/class-cache.md b/docs/book/pattern/class-cache.md
@@ -8,34 +8,40 @@ class being cached, and caches static properties.
 ## Quick Start
 
 ```php
-use Laminas\Cache\PatternFactory;
-
-$classCache = PatternFactory::factory('class', [
-    'class'   => 'MyClass',
-    'storage' => 'apc',
-]);
+use Laminas\Cache\Pattern\ClassCache;
+use Laminas\Cache\Pattern\PatternOptions;
+use Laminas\Cache\Storage\StorageInterface;
+
+/** @var StorageInterface $storage */
+$storage = null; // Can be any instance of StorageInterface
+
+$classCache = new ClassCache(
+    $storage,
+    new PatternOptions([
+        'class' => 'MyClass',
+    ])
+);
 ```
 
 ## Configuration Options
 
 Option | Data Type | Default Value | Description
 ------ | --------- | ------------- | -----------
-`storage` | `string | array | Laminas\Cache\Storage\StorageInterface` | none | Adapter used for reading and writing cached data.
+`storage` | `string | array | Laminas\Cache\Storage\StorageInterface` | none | **deprecated** Adapter used for reading and writing cached data.
 `class` | `string` | none | Name of the class for which to cache method output.
-`cache_output` | `boolean` | `true` | Whether or not to cache method output.
-`cache_by_default` | `boolean` | `true` | Cache all method calls by default.
+`cache_output` | `bool` | `true` | Whether or not to cache method output.
+`cache_by_default` | `bool` | `true` | Cache all method calls by default.
 `class_cache_methods` | `array` | `[]` | List of methods to cache (if `cache_by_default` is disabled).
 `class_non_cache_methods` | `array` | `[]` | List of methods to omit from caching (if `cache_by_default` is enabled).
 
 ## Available Methods
 
-In addition to the methods defined in `PatternInterface`, this implementation
+In addition to the methods defined in `PatternInterface` and the `StorageCapableInterface`, this implementation
 exposes the following methods.
 
 ```php
 namespace Laminas\Cache\Pattern;
 
-use Laminas\Cache;
 use Laminas\Cache\Exception;
 
 class ClassCache extends CallbackCache
@@ -134,14 +140,23 @@ class ClassCache extends CallbackCache
 ### Caching of Import Feeds
 
 ```php
-$cachedFeedReader = Laminas\Cache\PatternFactory::factory('class', [
-    'class'   => 'Laminas\Feed\Reader\Reader',
-    'storage' => 'apc',
-
-    // The feed reader doesn't output anything,
-    // so the output doesn't need to be caught and cached:
-    'cache_output' => false,
-]);
+use Laminas\Cache\Pattern\ClassCache;
+use Laminas\Cache\Pattern\PatternOptions;
+use Laminas\Cache\Storage\StorageInterface;
+
+/** @var StorageInterface $storage */
+$storage = null; // Can be any instance of StorageInterface
+
+$cachedFeedReader = new ClassCache(
+    $storage,
+    new PatternOptions([
+        'class' => \Laminas\Feed\Reader\Reader::class,
+
+        // The feed reader doesn't output anything,
+        // so the output doesn't need to be caught and cached:
+        'cache_output' => false,
+    ])
+);
 
 $feed = $cachedFeedReader->call("import", array('http://www.planet-php.net/rdf/'));
 

diff --git a/docs/book/pattern/intro.md b/docs/book/pattern/intro.md
@@ -26,35 +26,30 @@ Pattern objects can either be created from the provided `Laminas\Cache\PatternFa
 by instantiating one of the `Laminas\Cache\Pattern\*Cache` classes.
 
 ```php
-// Via the factory:
-$callbackCache = Laminas\Cache\PatternFactory::factory('callback', [
-    'storage' => 'apc',
-]);
+use Laminas\Cache\Pattern\CallbackCache;
+use Laminas\Cache\Pattern\PatternOptions;
+use Laminas\Cache\Storage\StorageInterface;
+
+/** @var StorageInterface $storage */
+$storage = null; // Can be any instance of StorageInterface
 
 // Or the equivalent manual instantiation:
-$callbackCache = new Laminas\Cache\Pattern\CallbackCache();
-$callbackCache->setOptions(new Laminas\Cache\Pattern\PatternOptions([
-    'storage' => 'apc',
-]));
+$callbackCache = new CallbackCache(
+    $storage,
+    new PatternOptions()
+);
 ```
 
 ## Available Methods
 
-The following methods are implemented by `Laminas\Cache\Pattern\AbstractPattern`.
+The following methods are implemented by every cache pattern.
 Please read documentation of specific patterns to get more information.
 
 ```php
 namespace Laminas\Cache\Pattern;
 
 interface PatternInterface
 {
-    /**
-     * Set pattern options
-     *
-     * @param  PatternOptions $options
-     * @return PatternInterface
-     */
-    public function setOptions(PatternOptions $options);
 
     /**
      * Get all pattern options
@@ -64,3 +59,16 @@ interface PatternInterface
     public function getOptions();
 }
 ```
+
+There are cache patterns which depend on a storage. In this case, these adapters implement the `StorageCapableInterface`:
+
+```php
+namespace Laminas\Cache\Pattern;
+
+use Laminas\Cache\Storage\StorageInterface;
+
+interface StorageCapableInterface extends PatternInterface
+{
+    public function getStorage(): ?StorageInterface;
+}
+```
diff --git a/docs/book/pattern/object-cache.md b/docs/book/pattern/object-cache.md
@@ -7,32 +7,39 @@ public properties.
 ## Quick Start
 
 ```php
+use Laminas\Cache\Pattern\ObjectCache;
+use Laminas\Cache\Pattern\PatternOptions;
+use Laminas\Cache\Storage\StorageInterface;
 use stdClass;
-use Laminas\Cache\PatternFactory;
+
+/** @var StorageInterface $storage */
+$storage = null; // Can be any instance of StorageInterface
 
 $object      = new stdClass();
-$objectCache = PatternFactory::factory('object', [
-    'object'  => $object,
-    'storage' => 'apc'
-]);
+$objectCache = new ObjectCache(
+    $storage,
+    new PatternOptions([
+      'object'  => $object,
+    ])
+);
 ```
 
 ## Configuration Options
 
 Option | Data Type | Default Value | Description
 ------ | --------- | ------------- | -----------
-`storage` | `string | array | Laminas\Cache\Storage\StorageInterface` | none | Adapter used for reading and writing cached data.
+`storage` | `string | array | Laminas\Cache\Storage\StorageInterface` | none | **deprecated** Adapter used for reading and writing cached data.
 `object` | `object` | none | The object for which to cache method calls.
 `object_key` | `null | string` | Class name of object | Hopefully unique!
-`cache_output` | `boolean` | `true` | Whether or not to cache method output.
-`cache_by_default` | `boolean` | `true` | Cache all method calls by default.
+`cache_output` | `bool` | `true` | Whether or not to cache method output.
+`cache_by_default` | `bool` | `true` | Cache all method calls by default.
 `object_cache_methods` | `array` | `[]` | List of methods to cache (if `cache_by_default` is disabled).
 `object_non_cache_methods` | `array` | `[]` | List of methods to blacklist (if `cache_by_default` is enabled).
-`object_cache_magic_properties` | `boolean` | `false` | Whether or not to cache properties exposed by method overloading.
+`object_cache_magic_properties` | `bool` | `false` | Whether or not to cache properties exposed by method overloading.
 
 ## Available Methods
 
-In addition to the methods defined in `PatternInterface`, this implementation
+In addition to the methods defined in `PatternInterface` and the `StorageCapableInterface`, this implementation
 defines the following methods.
 
 ```php
@@ -153,16 +160,24 @@ class ObjectCache extends CallbackCache
 ### Caching a Filter
 
 ```php
-$filter       = new Laminas\Filter\RealPath();
-$cachedFilter = Laminas\Cache\PatternFactory::factory('object', [
-    'object'     => $filter,
-    'object_key' => 'RealpathFilter',
-    'storage'    => 'apc',
-
-    // The realpath filter doesn't output anything
-    // so the output don't need to be caught and cached
-    'cache_output' => false,
-]);
+use Laminas\Cache\Pattern\ObjectCache;
+use Laminas\Cache\Pattern\PatternOptions;
+use Laminas\Cache\Storage\StorageInterface;
+
+/** @var StorageInterface $storage */
+$storage      = null; // Can be any instance of StorageInterface
+$filter       = new \Laminas\Filter\RealPath();
+$cachedFilter = new ObjectCache(
+    $storage,
+    new PatternOptions([
+        'object'     => $filter,
+        'object_key' => 'RealpathFilter',
+
+        // The realpath filter doesn't output anything
+        // so the output don't need to be caught and cached
+        'cache_output' => false,
+    ])
+);
 
 $path = $cachedFilter->call("filter", ['/www/var/path/../../mypath']);