[Cache] Add [Taggable]CacheInterface, the easiest way to use a cache

nicolas-grekas · nicolas-grekas · commit c33e47c0e52f · 2018-04-17T15:08:13.000+02:00
diff --git a/src/Symfony/Bundle/FrameworkBundle/Resources/config/cache.xml b/src/Symfony/Bundle/FrameworkBundle/Resources/config/cache.xml
@@ -15,6 +15,10 @@
             <argument type="service" id="cache.app" />
         </service>
 
+        <service id="cache.app.taggable" class="Symfony\Component\Cache\Adapter\TagAwareAdapter">
+            <argument type="service" id="cache.app" />
+        </service>
+
         <service id="cache.system" parent="cache.adapter.system" public="true">
             <tag name="cache.pool" />
         </service>
@@ -122,7 +126,9 @@
         <service id="cache.global_clearer" parent="cache.default_clearer" public="true" />
         <service id="cache.app_clearer" alias="cache.default_clearer" public="true" />
         <service id="Psr\Cache\CacheItemPoolInterface" alias="cache.app" />
+        <service id="Symfony\Component\Cache\TaggableCacheInterface" alias="cache.app.taggable" />
         <service id="Psr\SimpleCache\CacheInterface" alias="cache.app.simple" />
         <service id="Symfony\Component\Cache\Adapter\AdapterInterface" alias="cache.app" />
+        <service id="Symfony\Component\Cache\CacheInterface" alias="cache.app" />
     </services>
 </container>
diff --git a/src/Symfony/Component/Cache/Adapter/AbstractAdapter.php b/src/Symfony/Component/Cache/Adapter/AbstractAdapter.php
@@ -15,17 +15,20 @@
 use Psr\Log\LoggerAwareInterface;
 use Psr\Log\LoggerInterface;
 use Psr\Log\NullLogger;
+use Symfony\Component\Cache\CacheInterface;
 use Symfony\Component\Cache\CacheItem;
 use Symfony\Component\Cache\Exception\InvalidArgumentException;
 use Symfony\Component\Cache\ResettableInterface;
 use Symfony\Component\Cache\Traits\AbstractTrait;
+use Symfony\Component\Cache\Traits\GetTrait;
 
 /**
  * @author Nicolas Grekas <p@tchwork.com>
  */
-abstract class AbstractAdapter implements AdapterInterface, LoggerAwareInterface, ResettableInterface
+abstract class AbstractAdapter implements AdapterInterface, CacheInterface, LoggerAwareInterface, ResettableInterface
 {
     use AbstractTrait;
+    use GetTrait;
 
     private static $apcuSupported;
     private static $phpFilesSupported;
diff --git a/src/Symfony/Component/Cache/Adapter/ArrayAdapter.php b/src/Symfony/Component/Cache/Adapter/ArrayAdapter.php
@@ -13,16 +13,19 @@
 
 use Psr\Cache\CacheItemInterface;
 use Psr\Log\LoggerAwareInterface;
+use Symfony\Component\Cache\CacheInterface;
 use Symfony\Component\Cache\CacheItem;
 use Symfony\Component\Cache\ResettableInterface;
 use Symfony\Component\Cache\Traits\ArrayTrait;
+use Symfony\Component\Cache\Traits\GetTrait;
 
 /**
  * @author Nicolas Grekas <p@tchwork.com>
  */
-class ArrayAdapter implements AdapterInterface, LoggerAwareInterface, ResettableInterface
+class ArrayAdapter implements AdapterInterface, CacheInterface, LoggerAwareInterface, ResettableInterface
 {
     use ArrayTrait;
+    use GetTrait;
 
     private $createCacheItem;
 
diff --git a/src/Symfony/Component/Cache/Adapter/ChainAdapter.php b/src/Symfony/Component/Cache/Adapter/ChainAdapter.php
@@ -13,10 +13,12 @@
 
 use Psr\Cache\CacheItemInterface;
 use Psr\Cache\CacheItemPoolInterface;
+use Symfony\Component\Cache\CacheInterface;
 use Symfony\Component\Cache\CacheItem;
 use Symfony\Component\Cache\Exception\InvalidArgumentException;
 use Symfony\Component\Cache\PruneableInterface;
 use Symfony\Component\Cache\ResettableInterface;
+use Symfony\Component\Cache\Traits\GetTrait;
 
 /**
  * Chains several adapters together.
@@ -26,8 +28,10 @@
  *
  * @author Kévin Dunglas <dunglas@gmail.com>
  */
-class ChainAdapter implements AdapterInterface, PruneableInterface, ResettableInterface
+class ChainAdapter implements AdapterInterface, CacheInterface, PruneableInterface, ResettableInterface
 {
+    use GetTrait;
+
     private $adapters = array();
     private $adapterCount;
     private $saveUp;
diff --git a/src/Symfony/Component/Cache/Adapter/PhpArrayAdapter.php b/src/Symfony/Component/Cache/Adapter/PhpArrayAdapter.php
@@ -13,10 +13,12 @@
 
 use Psr\Cache\CacheItemInterface;
 use Psr\Cache\CacheItemPoolInterface;
+use Symfony\Component\Cache\CacheInterface;
 use Symfony\Component\Cache\CacheItem;
 use Symfony\Component\Cache\Exception\InvalidArgumentException;
 use Symfony\Component\Cache\PruneableInterface;
 use Symfony\Component\Cache\ResettableInterface;
+use Symfony\Component\Cache\Traits\GetTrait;
 use Symfony\Component\Cache\Traits\PhpArrayTrait;
 
 /**
@@ -26,9 +28,10 @@
  * @author Titouan Galopin <galopintitouan@gmail.com>
  * @author Nicolas Grekas <p@tchwork.com>
  */
-class PhpArrayAdapter implements AdapterInterface, PruneableInterface, ResettableInterface
+class PhpArrayAdapter implements AdapterInterface, CacheInterface, PruneableInterface, ResettableInterface
 {
     use PhpArrayTrait;
+    use GetTrait;
 
     private $createCacheItem;
 
diff --git a/src/Symfony/Component/Cache/Adapter/ProxyAdapter.php b/src/Symfony/Component/Cache/Adapter/ProxyAdapter.php
@@ -13,17 +13,20 @@
 
 use Psr\Cache\CacheItemInterface;
 use Psr\Cache\CacheItemPoolInterface;
+use Symfony\Component\Cache\CacheInterface;
 use Symfony\Component\Cache\CacheItem;
 use Symfony\Component\Cache\PruneableInterface;
 use Symfony\Component\Cache\ResettableInterface;
+use Symfony\Component\Cache\Traits\GetTrait;
 use Symfony\Component\Cache\Traits\ProxyTrait;
 
 /**
  * @author Nicolas Grekas <p@tchwork.com>
  */
-class ProxyAdapter implements AdapterInterface, PruneableInterface, ResettableInterface
+class ProxyAdapter implements AdapterInterface, CacheInterface, PruneableInterface, ResettableInterface
 {
     use ProxyTrait;
+    use GetTrait;
 
     private $namespace;
     private $namespaceLen;
diff --git a/src/Symfony/Component/Cache/Adapter/TagAwareAdapter.php b/src/Symfony/Component/Cache/Adapter/TagAwareAdapter.php
@@ -16,16 +16,19 @@
 use Symfony\Component\Cache\CacheItem;
 use Symfony\Component\Cache\PruneableInterface;
 use Symfony\Component\Cache\ResettableInterface;
+use Symfony\Component\Cache\TaggableCacheInterface;
+use Symfony\Component\Cache\Traits\GetTrait;
 use Symfony\Component\Cache\Traits\ProxyTrait;
 
 /**
  * @author Nicolas Grekas <p@tchwork.com>
  */
-class TagAwareAdapter implements TagAwareAdapterInterface, PruneableInterface, ResettableInterface
+class TagAwareAdapter implements TagAwareAdapterInterface, TaggableCacheInterface, PruneableInterface, ResettableInterface
 {
     const TAGS_PREFIX = "\0tags\0";
 
     use ProxyTrait;
+    use GetTrait;
 
     private $deferred = array();
     private $createCacheItem;
@@ -55,6 +58,7 @@ function ($key, $value, CacheItem $protoItem) {
         );
         $this->setCacheItemTags = \Closure::bind(
             function (CacheItem $item, $key, array &$itemTags) {
+                $item->isTaggable = true;
                 if (!$item->isHit) {
                     return $item;
                 }
diff --git a/src/Symfony/Component/Cache/Adapter/TraceableAdapter.php b/src/Symfony/Component/Cache/Adapter/TraceableAdapter.php
@@ -12,8 +12,10 @@
 namespace Symfony\Component\Cache\Adapter;
 
 use Psr\Cache\CacheItemInterface;
+use Symfony\Component\Cache\CacheInterface;
 use Symfony\Component\Cache\PruneableInterface;
 use Symfony\Component\Cache\ResettableInterface;
+use Symfony\Component\Cache\Traits\GetTrait;
 
 /**
  * An adapter that collects data about all cache calls.
@@ -22,8 +24,10 @@
  * @author Tobias Nyholm <tobias.nyholm@gmail.com>
  * @author Nicolas Grekas <p@tchwork.com>
  */
-class TraceableAdapter implements AdapterInterface, PruneableInterface, ResettableInterface
+class TraceableAdapter implements AdapterInterface, CacheInterface, PruneableInterface, ResettableInterface
 {
+    use GetTrait;
+
     protected $pool;
     private $calls = array();
 
diff --git a/src/Symfony/Component/Cache/Adapter/TraceableTagAwareAdapter.php b/src/Symfony/Component/Cache/Adapter/TraceableTagAwareAdapter.php
@@ -11,10 +11,12 @@
 
 namespace Symfony\Component\Cache\Adapter;
 
+use Symfony\Component\Cache\TaggableCacheInterface;
+
 /**
  * @author Robin Chalas <robin.chalas@gmail.com>
  */
-class TraceableTagAwareAdapter extends TraceableAdapter implements TagAwareAdapterInterface
+class TraceableTagAwareAdapter extends TraceableAdapter implements TaggableCacheInterface, TagAwareAdapterInterface
 {
     public function __construct(TagAwareAdapterInterface $pool)
     {
diff --git a/src/Symfony/Component/Cache/CHANGELOG.md b/src/Symfony/Component/Cache/CHANGELOG.md
@@ -1,6 +1,12 @@
 CHANGELOG
 =========
 
+4.1.0
+-----
+
+ * added `CacheInterface` and `TaggableCacheInterface`
+ * throw `LogicException` when `CacheItem::tag()` is called on an item coming from a non tag-aware pool
+
 3.4.0
 -----
 
diff --git a/src/Symfony/Component/Cache/CacheInterface.php b/src/Symfony/Component/Cache/CacheInterface.php
@@ -0,0 +1,44 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Cache;
+
+use Psr\Cache\CacheItemInterface;
+
+/**
+ * Gets and stores items from a cache.
+ *
+ * On cache misses, a callback is called that should return the missing value.
+ * It is given two arguments:
+ * - the missing cache key
+ * - the corresponding PSR-6 CacheItemInterface object,
+ *   allowing time-based expiration control.
+ *
+ * If you need tag-based invalidation, use TaggableCacheInterface instead.
+ *
+ * @author Nicolas Grekas <p@tchwork.com>
+ */
+interface CacheInterface
+{
+    /**
+     * @param callable(CacheItemInterface $item):mixed $callback Should return the computed value for the given key/item
+     *
+     * @return mixed The value corresponding to the provided key
+     */
+    public function get(string $key, callable $callback);
+
+    /**
+     * @param callable(CacheItemInterface $item):mixed $callback Should return the computed value for the given key/item
+     *
+     * @return iterable The values corresponding to the provided keys
+     */
+    public function getMultiple(iterable $keys, callable $callback): iterable;
+}
diff --git a/src/Symfony/Component/Cache/CacheItem.php b/src/Symfony/Component/Cache/CacheItem.php
@@ -14,6 +14,7 @@
 use Psr\Cache\CacheItemInterface;
 use Psr\Log\LoggerInterface;
 use Symfony\Component\Cache\Exception\InvalidArgumentException;
+use Symfony\Component\Cache\Exception\LogicException;
 
 /**
  * @author Nicolas Grekas <p@tchwork.com>
@@ -29,6 +30,7 @@ final class CacheItem implements CacheItemInterface
     protected $prevTags = array();
     protected $innerItem;
     protected $poolHash;
+    protected $isTaggable = false;
 
     /**
      * {@inheritdoc}
@@ -109,7 +111,10 @@ public function expiresAfter($time)
      */
     public function tag($tags)
     {
-        if (!is_array($tags)) {
+        if (!$this->isTaggable) {
+            throw new LogicException(sprintf('Cache item "%s" comes from a non tag-aware pool: you cannot tag it.', $this->key));
+        }
+        if (!\is_iterable($tags)) {
             $tags = array($tags);
         }
         foreach ($tags as $tag) {
diff --git a/src/Symfony/Component/Cache/Exception/LogicException.php b/src/Symfony/Component/Cache/Exception/LogicException.php
@@ -0,0 +1,19 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Cache\Exception;
+
+use Psr\Cache\InvalidArgumentException as Psr6CacheInterface;
+use Psr\SimpleCache\InvalidArgumentException as SimpleCacheInterface;
+
+class LogicException extends \LogicException implements Psr6CacheInterface, SimpleCacheInterface
+{
+}
diff --git a/src/Symfony/Component/Cache/TaggableCacheInterface.php b/src/Symfony/Component/Cache/TaggableCacheInterface.php
@@ -0,0 +1,42 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Cache;
+
+/**
+ * Gets and stores items from a tag-aware cache.
+ *
+ * On cache misses, a callback is called that should return the missing value.
+ * It is given two arguments:
+ * - the missing cache key
+ * - the corresponding Symfony CacheItem object,
+ *   allowing time-based *and* tags-based expiration control
+ *
+ * If you don't need tags-based invalidation, use CacheInterface instead.
+ *
+ * @author Nicolas Grekas <p@tchwork.com>
+ */
+interface TaggableCacheInterface extends CacheInterface
+{
+    /**
+     * @param callable(CacheItem $item):mixed $callback Should return the computed value for the given key/item
+     *
+     * @return mixed The value corresponding to the provided key
+     */
+    public function get(string $key, callable $callback);
+
+    /**
+     * @param callable(CacheItem $item):mixed $callback Should return the computed value for the given key/item
+     *
+     * @return iterable The values corresponding to the provided keys
+     */
+    public function getMultiple(iterable $keys, callable $callback): iterable;
+}
diff --git a/src/Symfony/Component/Cache/Tests/Adapter/AdapterTestCase.php b/src/Symfony/Component/Cache/Tests/Adapter/AdapterTestCase.php
diff --git a/src/Symfony/Component/Cache/Tests/Adapter/PhpArrayAdapterTest.php b/src/Symfony/Component/Cache/Tests/Adapter/PhpArrayAdapterTest.php
diff --git a/src/Symfony/Component/Cache/Tests/CacheItemTest.php b/src/Symfony/Component/Cache/Tests/CacheItemTest.php
diff --git a/src/Symfony/Component/Cache/Traits/GetTrait.php b/src/Symfony/Component/Cache/Traits/GetTrait.php

Original file line number	Diff line number	Diff line change
`@@ -11,10 +11,12 @@`
`11`	`11`
`12`	`12`	`namespace Symfony\Component\Cache\Adapter;`
`13`	`13`
	`14`	`+use Symfony\Component\Cache\TaggableCacheInterface;`
	`15`	`+`
`14`	`16`	`/**`
`15`	`17`	`* @author Robin Chalas <robin.chalas@gmail.com>`
`16`	`18`	`*/`
`17`		`-class TraceableTagAwareAdapter extends TraceableAdapter implements TagAwareAdapterInterface`
	`19`	`+class TraceableTagAwareAdapter extends TraceableAdapter implements TaggableCacheInterface, TagAwareAdapterInterface`
`18`	`20`	`{`
`19`	`21`	`public function __construct(TagAwareAdapterInterface $pool)`
`20`	`22`	`{`