diff --git a/CacheInterface.php b/CacheInterface.php index 70cb0d5..3e4aaf6 100644 --- a/CacheInterface.php +++ b/CacheInterface.php @@ -29,20 +29,22 @@ interface CacheInterface * 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|CallbackInterface $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 - * @param array &$metadata The metadata of the cached item {@see ItemInterface::getMetadata()} + * @template T * - * @return mixed + * @param string $key The key of the item to retrieve from the cache + * @param (callable(CacheItemInterface,bool):T)|(callable(ItemInterface,bool):T)|CallbackInterface $callback + * @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 + * @param array &$metadata The metadata of the cached item {@see ItemInterface::getMetadata()} + * + * @return T * * @throws InvalidArgumentException When $key is not valid or when $beta is negative */ - public function get(string $key, callable $callback, ?float $beta = null, ?array &$metadata = null); + public function get(string $key, callable $callback, ?float $beta = null, ?array &$metadata = null): mixed; /** * Removes an item from the pool. diff --git a/CacheTrait.php b/CacheTrait.php index b9feafb..4c5449b 100644 --- a/CacheTrait.php +++ b/CacheTrait.php @@ -25,28 +25,20 @@ class_exists(InvalidArgumentException::class); */ trait CacheTrait { - /** - * {@inheritdoc} - * - * @return mixed - */ - public function get(string $key, callable $callback, ?float $beta = null, ?array &$metadata = null) + public function get(string $key, callable $callback, ?float $beta = null, ?array &$metadata = null): mixed { return $this->doGet($this, $key, $callback, $beta, $metadata); } - /** - * {@inheritdoc} - */ public function delete(string $key): bool { return $this->deleteItem($key); } - private function doGet(CacheItemPoolInterface $pool, string $key, callable $callback, ?float $beta, ?array &$metadata = null, ?LoggerInterface $logger = null) + private function doGet(CacheItemPoolInterface $pool, string $key, callable $callback, ?float $beta, ?array &$metadata = null, ?LoggerInterface $logger = null): mixed { - if (0 > $beta = $beta ?? 1.0) { - throw new class(sprintf('Argument "$beta" provided to "%s::get()" must be a positive number, %f given.', static::class, $beta)) extends \InvalidArgumentException implements InvalidArgumentException { }; + if (0 > $beta ??= 1.0) { + throw new class(\sprintf('Argument "$beta" provided to "%s::get()" must be a positive number, %f given.', static::class, $beta)) extends \InvalidArgumentException implements InvalidArgumentException {}; } $item = $pool->getItem($key); @@ -60,9 +52,9 @@ private function doGet(CacheItemPoolInterface $pool, string $key, callable $call if ($recompute = $ctime && $expiry && $expiry <= ($now = microtime(true)) - $ctime / 1000 * $beta * log(random_int(1, \PHP_INT_MAX) / \PHP_INT_MAX)) { // force applying defaultLifetime to expiry $item->expiresAt(null); - $logger && $logger->info('Item "{key}" elected for early recomputation {delta}s before its expiration', [ + $logger?->info('Item "{key}" elected for early recomputation {delta}s before its expiration', [ 'key' => $key, - 'delta' => sprintf('%.1f', $expiry - $now), + 'delta' => \sprintf('%.1f', $expiry - $now), ]); } } diff --git a/CallbackInterface.php b/CallbackInterface.php index 7dae2aa..15941e9 100644 --- a/CallbackInterface.php +++ b/CallbackInterface.php @@ -17,6 +17,8 @@ * Computes and returns the cached value of an item. * * @author Nicolas Grekas + * + * @template T */ interface CallbackInterface { @@ -24,7 +26,7 @@ interface CallbackInterface * @param CacheItemInterface|ItemInterface $item The item to compute the value for * @param bool &$save Should be set to false when the value should not be saved in the pool * - * @return mixed The computed value for the passed item + * @return T The computed value for the passed item */ - public function __invoke(CacheItemInterface $item, bool &$save); + public function __invoke(CacheItemInterface $item, bool &$save): mixed; } diff --git a/ItemInterface.php b/ItemInterface.php index 10c0488..8c4c512 100644 --- a/ItemInterface.php +++ b/ItemInterface.php @@ -54,7 +54,7 @@ interface ItemInterface extends CacheItemInterface * @throws InvalidArgumentException When $tag is not valid * @throws CacheException When the item comes from a pool that is not tag-aware */ - public function tag($tags): self; + public function tag(string|iterable $tags): static; /** * Returns a list of metadata info that were saved alongside with the cached value. diff --git a/NamespacedPoolInterface.php b/NamespacedPoolInterface.php new file mode 100644 index 0000000..cd67bc0 --- /dev/null +++ b/NamespacedPoolInterface.php @@ -0,0 +1,31 @@ + + * + * 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\InvalidArgumentException; + +/** + * Enables namespace-based invalidation by prefixing keys with backend-native namespace separators. + * + * Note that calling `withSubNamespace()` MUST NOT mutate the pool, but return a new instance instead. + * + * When tags are used, they MUST ignore sub-namespaces. + * + * @author Nicolas Grekas + */ +interface NamespacedPoolInterface +{ + /** + * @throws InvalidArgumentException If the namespace contains characters found in ItemInterface's RESERVED_CHARACTERS + */ + public function withSubNamespace(string $namespace): static; +} diff --git a/README.md b/README.md index 7085a69..ffe0833 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ Symfony Cache Contracts A set of abstractions extracted out of the Symfony components. -Can be used to build on semantics that the Symfony components proved useful - and +Can be used to build on semantics that the Symfony components proved useful and that already have battle tested implementations. See https://github.com/symfony/contracts/blob/main/README.md for more information. diff --git a/TagAwareCacheInterface.php b/TagAwareCacheInterface.php index 7c4cf11..8e0b6be 100644 --- a/TagAwareCacheInterface.php +++ b/TagAwareCacheInterface.php @@ -34,5 +34,5 @@ interface TagAwareCacheInterface extends CacheInterface * * @throws InvalidArgumentException When $tags is not valid */ - public function invalidateTags(array $tags); + public function invalidateTags(array $tags): bool; } diff --git a/composer.json b/composer.json index 9f45e17..b713c29 100644 --- a/composer.json +++ b/composer.json @@ -16,11 +16,8 @@ } ], "require": { - "php": ">=7.2.5", - "psr/cache": "^1.0|^2.0|^3.0" - }, - "suggest": { - "symfony/cache-implementation": "" + "php": ">=8.1", + "psr/cache": "^3.0" }, "autoload": { "psr-4": { "Symfony\\Contracts\\Cache\\": "" } @@ -28,7 +25,7 @@ "minimum-stability": "dev", "extra": { "branch-alias": { - "dev-main": "2.5-dev" + "dev-main": "3.6-dev" }, "thanks": { "name": "symfony/contracts",