From e899545ee62e4954ef4d35d06f46a42e5b659df5 Mon Sep 17 00:00:00 2001 From: Nicolas Grekas Date: Mon, 12 May 2025 16:18:59 +0200 Subject: [PATCH] [Cache] Tell about namespace-based invalidation --- components/cache.rst | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/components/cache.rst b/components/cache.rst index 4873fb7abc7..e2bce1cf812 100644 --- a/components/cache.rst +++ b/components/cache.rst @@ -84,6 +84,33 @@ generate and return the value:: Use cache tags to delete more than one key at the time. Read more at :doc:`/components/cache/cache_invalidation`. +Creating Sub-Namespaces +----------------------- + +All cache adapters provided by the component implement the +:method:`Symfony\\Contracts\\Cache\\NamespacedPoolInterface::withSubNamespace` method +from the :class:`Symfony\\Contracts\\Cache\\NamespacedPoolInterface`. + +.. versionadded:: 7.3 + + Support for ``NamespacedPoolInterface`` was added in Symfony 7.3. + +This method allows namespacing cached items by transparently prefixing their keys:: + + $subCache = $cache->withSubNamespace('foo'); + + $subCache->get('my_cache_key', function (ItemInterface $item): string { + $item->expiresAfter(3600); + + return '...'; + }); + +In this example, cache item keyed ``my_cache_key`` will be transparently stored within +the cache pool under a logical namespace called ``foo``. + +Sub-namespacing allows implementing namespace-based cache invalidation, where the name +of a namespace is computed by hashing some context info. + .. _cache_stampede-prevention: Stampede Prevention