[Cache] add CacheInterface::delete() + improve CacheTrait

Author: nicolas-grekas

CacheInterface.php

@@ -11,31 +11,46 @@
 
 namespace Symfony\Contracts\Cache;
 
+use Psr\Cache\CacheItemInterface;
 use Psr\Cache\InvalidArgumentException;
 
 /**
- * Gets/Stores items from/to a cache.
- *
- * On cache misses, a callback is called that should return the missing value.
- * This callback is given an ItemInterface object corresponding to the needed key,
- * that could be used e.g. for expiration control.
+ * Covers most simple to advanced caching needs.
  *
  * @author Nicolas Grekas <p@tchwork.com>
  */
 interface CacheInterface
 {
  /**
- * @param string $key The key of the item to retrieve from the cache
- * @param callable(ItemInterface):mixed $callback Should return the computed value for the given key/item
- * @param float|null $beta A float that, as it grows, controls the likeliness of triggering
- * early expiration. 0 disables it, INF forces immediate expiration.
- * The default (or providing null) is implementation dependent but should
- * typically be 1.0, which should provide optimal stampede protection.
- * See https://en.wikipedia.org/wiki/Cache_stampede#Probabilistic_early_expiration
+ * Fetches a value from the pool or computes it if not found.
+ *
+ * On cache misses, a callback is called that should return the missing value.
+ * This callback is given a PSR-6 CacheItemInterface instance corresponding to the
+ * requested key, that could be used e.g. for expiration control. It could also
+ * be an ItemInterface instance when its additional features are needed.
+ *
+ * @param string $key The key of the item to retrieve from the cache
+ * @param callable(CacheItemInterface):mixed $callback Should return the computed value for the given key/item
+ * @param float|null $beta A float that, as it grows, controls the likeliness of triggering
+ * early expiration. 0 disables it, INF forces immediate expiration.
+ * The default (or providing null) is implementation dependent but should
+ * typically be 1.0, which should provide optimal stampede protection.
+ * See https://en.wikipedia.org/wiki/Cache_stampede#Probabilistic_early_expiration
  *
  * @return mixed The value corresponding to the provided key
  *
  * @throws InvalidArgumentException When $key is not valid or when $beta is negative
  */
  public function get(string $key, callable $callback, float $beta = null);
+
+ /**
+ * Removes an item from the pool.
+ *
+ * @param string $key The key to delete
+ *
+ * @throws InvalidArgumentException When $key is not valid
+ *
+ * @return bool True if the item was successfully removed, false if there was any error
+ */
+ public function delete(string $key): bool;
 }

CacheTrait.php

@@ -0,0 +1,67 @@
+<?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\Contracts\Cache;
+
+use Psr\Cache\CacheItemPoolInterface;
+use Psr\Cache\InvalidArgumentException;
+
+/**
+ * An implementation of CacheInterface for PSR-6 CacheItemPoolInterface classes.
+ *
+ * @author Nicolas Grekas <p@tchwork.com>
+ */
+trait CacheTrait
+{
+ /**
+ * {@inheritdoc}
+ */
+ public function get(string $key, callable $callback, float $beta = null)
+ {
+ return $this->doGet($this, $key, $callback, $beta);
+ }
+
+ /**
+ * {@inheritdoc}
+ */
+ public function delete(string $key): bool
+ {
+ return $this->deleteItem($key);
+ }
+
+ private function doGet(CacheItemPoolInterface $pool, string $key, callable $callback, ?float $beta)
+ {
+ if (0 > $beta = $beta ?? 1.0) {
+ throw new class(sprintf('Argument "$beta" provided to "%s::get()" must be a positive number, %f given.', \get_class($this), $beta)) extends \InvalidArgumentException implements InvalidArgumentException {
+ };
+ }
+
+ $item = $pool->getItem($key);
+ $recompute = !$item->isHit() || INF === $beta;
+
+ if (!$recompute && $item instanceof ItemInterface) {
+ $metadata = $item->getMetadata();
+ $expiry = $metadata[ItemInterface::METADATA_EXPIRY] ?? false;
+ $ctime = $metadata[ItemInterface::METADATA_CTIME] ?? false;
+
+ if ($recompute = $ctime && $expiry && $expiry <= microtime(true) - $ctime / 1000 * $beta * log(random_int(1, PHP_INT_MAX) / PHP_INT_MAX)) {
+ // force applying defaultLifetime to expiry
+ $item->expiresAt(null);
+ }
+ }
+
+ if ($recompute) {
+ $pool->save($item->set($callback($item)));
+ }
+
+ return $item->get();
+ }
+}

GetForCacheItemPoolTrait.php

@@ -16,6 +16,8 @@
 use Psr\Cache\InvalidArgumentException;
 
 /**
+ * Augments PSR-6's CacheItemInterface with support for tags and metadata.
+ *
  * @author Nicolas Grekas <p@tchwork.com>
  */
 interface ItemInterface extends CacheItemInterface

ItemInterface.php

@@ -14,12 +14,19 @@
 use Psr\Cache\InvalidArgumentException;
 
 /**
- * Interface for invalidating cached items using tags.
+ * Allows invalidating cached items using tags.
  *
  * @author Nicolas Grekas <p@tchwork.com>
  */
 interface TagAwareCacheInterface extends CacheInterface
 {
+ /**
+ * {@inheritdoc}
+ *
+ * @param callable(ItemInterface):mixed $callback Should return the computed value for the given key/item
+ */
+ public function get(string $key, callable $callback, float $beta = null);
+
  /**
  * Invalidates cached items using tags.
  *