diff --git a/components/cache.rst b/components/cache.rst index e7a44bb05e3..2bb5e60bd8b 100644 --- a/components/cache.rst +++ b/components/cache.rst @@ -6,13 +6,17 @@ The Cache Component =================== - The Cache component provides an extended `PSR-6`_ implementation for adding - cache to your applications. It is designed to have a low overhead and it - ships with ready to use adapters for the most common caching backends. + The Cache component provides an extended `PSR-6`_ implementation as well as + a `PSR-16`_ "Simple Cache" implementation for adding cache to your applications. + It is designed to have a low overhead and it ships with ready to use adapters + for the most common caching backends. .. versionadded:: 3.1 The Cache component was introduced in Symfony 3.1. +.. versionadded:: 3.3 + The PSR-16 "Simple Cache" implementation was introduced in Symfony 3.3. + Installation ------------ @@ -21,11 +25,113 @@ You can install the component in 2 different ways: * :doc:`Install it via Composer ` (``symfony/cache`` on `Packagist`_); * Use the official Git repository (https://github.com/symfony/cache). -Key Concepts ------------- +Cache (PSR-6) Versus Simple Cache (PSR-16) +------------------------------------------ + +This component includes *two* different approaches to caching: + +:ref:`PSR-6 Caching `: + A fully-featured cache system, which includes cache "pools", more advanced + cache "items", and :ref:`cache tagging for invalidation `. + +:ref:`PSR-16 Simple Caching `: + A simple way to store, fetch and remove items from a cache. + +Both methods support the *same* cache adapters and will give you very similar performance. + +.. tip:: + + The component also contains adapters to convert between PSR-6 and PSR-16 caches. + See :doc:`/components/cache/psr6_psr16_adapters`. + +.. _cache-component-psr16-caching: + +Simple Caching (PSR-16) +----------------------- + +This part of the component is an implementation of `PSR-16`_, which means that its +basic API is the same as defined in the standard. First, create a cache object from +one of the built-in cache classes. For example, to create a filesystem-based cache, +instantiate :class:`Symfony\\Component\\Cache\\Simple\\FilesystemCache`:: + + use Symfony\Component\Cache\Simple\FilesystemCache; + + $cache = new FilesystemCache(); + +Now you can create, retrieve, update and delete items using this object:: + + // save a new item in the cache + $cache->set('stats.num_products', 4711); + + // or set it with a custom ttl + // $cache->set('stats.num_products', 4711, 3600); + + // retrieve the cache item + if (!$cache->has('stats.num_products')) { + // ... item does not exists in the cache + } + + // retrieve the value stored by the item + $numProducts = $cache->get('stats.num_products'); + + // or specify a default value, if the key doesn't exist + // $numProducts = $cache->get('stats.num_products', 100); + + // remove the cache key + $cache->delete('stats.num_products'); + + // clear *all* cache keys + $cache->clear(); + +You can also work with multiple items at once:: + + $cache->setMultiple(array( + 'stats.num_products' => 4711, + 'stats.num_users' => 1356, + )); + + $stats = $cache->getMultiple(array( + 'stats.num_products', + 'stats.num_users', + )); -Before starting to use the Cache component, it's important that you learn the -meaning of some key concepts: + $cache->deleteMultiple(array( + 'stats.num_products', + 'stats.num_users', + )); + +Available Simple Cache (PSR-16) Classes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following cache adapters are available: + +.. tip:: + + To find out more about each of these classes, you can read the + :doc:`PSR-6 Cache Pool ` page. These "Simple" + (PSR-16) cache classes aren't identical to the PSR-6 Adapters on that page, but + each share constructor arguments and use-cases. + +* :class:`Symfony\\Component\\Cache\\Simple\\ApcuCache` +* :class:`Symfony\\Component\\Cache\\Simple\\ArrayCache` +* :class:`Symfony\\Component\\Cache\\Simple\\ChainCache` +* :class:`Symfony\\Component\\Cache\\Simple\\DoctrineCache` +* :class:`Symfony\\Component\\Cache\\Simple\\FilesystemCache` +* :class:`Symfony\\Component\\Cache\\Simple\\MemcachedCache` +* :class:`Symfony\\Component\\Cache\\Simple\\NullCache` +* :class:`Symfony\\Component\\Cache\\Simple\\PdoCache` +* :class:`Symfony\\Component\\Cache\\Simple\\PhpArrayCache` +* :class:`Symfony\\Component\\Cache\\Simple\\PhpFilesCache` +* :class:`Symfony\\Component\\Cache\\Simple\\RedisCache` +* :class:`Symfony\\Component\\Cache\\Simple\\TraceableCache` + +.. _cache-component-psr6-caching: + +More Advanced Caching (PSR-6) +----------------------------- + +To use the more-advanced, PSR-6 Caching abilities, you'll need to learn its key +concepts: **Item** A single unit of information stored as a key/value pair, where the key is @@ -39,11 +145,11 @@ meaning of some key concepts: filesystem, in a database, etc. The component provides several ready to use adapters for common caching backends (Redis, APCu, etc.) -Basic Usage ------------ +Basic Usage (PSR-6) +------------------- -This component is an implementation of `PSR-6`_, which means that its basic API -is the same as defined in the standard. Before starting to cache information, +This part of the component is an implementation of `PSR-6`_, which means that its +basic API is the same as defined in the standard. Before starting to cache information, create the cache pool using any of the built-in adapters. For example, to create a filesystem-based cache, instantiate :class:`Symfony\\Component\\Cache\\Adapter\\FilesystemAdapter`:: @@ -71,8 +177,10 @@ Now you can create, retrieve, update and delete items using this cache pool:: // remove the cache item $cache->deleteItem('stats.num_products'); -Advanced Usage --------------- +For a list of all of the supported adapters, see :doc:`/components/cache/cache_pools`. + +Advanced Usage (PSR-6) +---------------------- .. toctree:: :glob: @@ -81,4 +189,5 @@ Advanced Usage cache/* .. _`PSR-6`: http://www.php-fig.org/psr/psr-6/ +.. _`PSR-16`: http://www.php-fig.org/psr/psr-16/ .. _Packagist: https://packagist.org/packages/symfony/cache diff --git a/components/cache/cache_pools.rst b/components/cache/cache_pools.rst index f7fddbff78f..c0aaf82b393 100644 --- a/components/cache/cache_pools.rst +++ b/components/cache/cache_pools.rst @@ -5,8 +5,8 @@ single: Redis Cache single: PDO Cache, Doctrine DBAL Cache -Cache Pools -=========== +Cache Pools and Supported Adapters +================================== Cache Pools are the logical repositories of cache items. They perform all the common operations on items, such as saving them or looking for them. Cache pools @@ -88,8 +88,9 @@ This adapter stores the contents in the memory of a Redis server. Unlike the APC adapter, it's not limited to the shared memory of the current server, so you can store contents in a cluster of servers if needed. -It requires to have installed Redis and have created a connection that implements -the ``\Redis``, ``\RedisArray``, ``\RedisCluster`` or ``\Predis`` classes:: +Before you start, make sure you have Redis running and have created a connection +that implements the ``\Redis``, ``\RedisArray``, ``\RedisCluster`` or ``\Predis`` +classes:: use Symfony\Component\Cache\Adapter\RedisAdapter; @@ -108,6 +109,48 @@ helper allows creating a connection to a Redis server using a DSN configuration: $redisConnection = RedisAdapter::createConnection('redis://localhost'); + $cache = new RedisAdapter($redisConnection); + +See the method's docblock for more options. + +Memcached Cache Adapter +~~~~~~~~~~~~~~~~~~~~~~~ + +This adapter stores the contents into a set of `Memcached`_ servers. + +Before you start, make sure you have Memcached running and have created a +:phpclass:`Memcached` object:: + + use Symfony\Component\Cache\Adapter\MemcachedAdapter; + + $cache = new MemcachedAdapter( + // the object that stores a valid connection to your Memcached servers + \Memcached $client, + // the string prefixed to the keys of the items stored in this cache + $namespace = '', + // in seconds; applied to cache items that don't define their own lifetime + // 0 means to store the cache items indefinitely (i.e. until the Memcached memory is deleted) + $defaultLifetime = 0 + ); + +The :method:`Symfony\\Component\\Cache\\Adapter\\Memcached::createConnection` +helper allows creating a connection to a pool of Memcached server using a DSN configuration:: + + $memcachedClient = MemcachedAdapter::createConnection( + 'memcached://user:pass@localhost?weight=33', + + // options, including username, password and Memcached::OPT_* options + array('persistent_id' => '_products_cache') + ); + + // alternate syntax: array notations for the servers + $memcachedClient = MemcachedAdapter::createConnection(array( + array('192.168.1.100', 11211, 33), + array('192.168.1.101', 11211, 33) + )); + + $cache = new MemcachedAdapter($memcachedClient); + See the method's docblock for more options. PDO & Doctrine DBAL Cache Adapter @@ -156,6 +199,25 @@ where it was missing. Since it's not possible to know the expiry date and time of a cache item, the second optional argument of ``ChainAdapter`` is the default lifetime applied to those cache items (by default it's ``0``). +Traceable Adapter +~~~~~~~~~~~~~~~~~ + +This adapter wraps another adapter, and allows you to read a report of all of the +"calls" made to the adapter, including how long actions took, cache hits, misses +and more:: + + use Symfony\Component\Cache\Adapter\TraceableAdapter; + use Symfony\Component\Cache\Adapter\FilesystemAdapter; + + $fileCache = new FilesystemAdapter(); + + $cache = new TraceableAdapter($fileCache); + + // work with the $cache adapter like normal + + // returns an array of TraceableAdapterEvent describing the calls + $events = $cache->getCalls(); + Proxy Cache Adapter ~~~~~~~~~~~~~~~~~~~ @@ -279,3 +341,4 @@ when all items are successfully deleted):: $cacheIsEmpty = $cache->clear(); .. _`Doctrine Cache`: https://github.com/doctrine/cache +.. _`Memcached`: http://php.net/manual/en/book.memcached.php diff --git a/components/cache/psr6_psr16_adapters.rst b/components/cache/psr6_psr16_adapters.rst new file mode 100644 index 00000000000..4d818449618 --- /dev/null +++ b/components/cache/psr6_psr16_adapters.rst @@ -0,0 +1,86 @@ +.. index:: + single: Cache + single: Performance + single: Components; Cache + +Adapters For Interoperability between PSR-6 and PSR-16 Cache +============================================================ + +Sometimes, you may have a Cache object that implements the :ref:`PSR-16 ` +standard, but need to pass it to an object that expects a :ref:`PSR-6 ` +cache adapter. Or, you might have the opposite situation. The cache component contains +two classes for bidirectional interoperability between PSR-6 and PSR-16 caches. + +Using a PSR-16 Cache Object as a PSR-6 Cache +-------------------------------------------- + +Suppose you want to work with a class that requires a PSR-6 Cache pool object. For +example:: + + use Psr\Cache\CacheItemPoolInterface; + + // just a made-up class for the example + class GitHubApiClient + { + // ... + + // this requires a PSR-6 cache object + public function __construct(CacheItemPoolInterface $cachePool) + { + // ... + } + } + +But, you already have a PSR-16 cache object, and you'd like to pass this to the class +instead. No problem! The Cache component provides the +:class:`Symfony\\Component\\Cache\\Adapter\\SimpleCacheAdapter` class for exactly +this use-case:: + + use Symfony\Component\Cache\Simple\FilesystemCache; + use Symfony\Component\Cache\Adapter\SimpleCacheAdapter + + // the PSR-16 cache object that you want to use + $psr16Cache = new FilesystemCache(); + + // a PSR-6 cache that uses your cache internally! + $psr6Cache = new SimpleCacheAdapter($psr16Cache); + + // now use this wherever you want + $githubApiClient = new GitHubApiClient($psr6Cache); + +Using a PSR-6 Cache Object as a PSR-16 Cache +-------------------------------------------- + +Suppose you want to work with a class that requires a PSR-16 Cache object. For +example:: + + use Psr\SimpleCache\CacheInterface; + + // just a made-up class for the example + class GitHubApiClient + { + // ... + + // this requires a PSR-16 cache object + public function __construct(CacheInterface $cache) + { + // ... + } + } + +But, you already have a PSR-6 cache pool object, and you'd like to pass this to +the class instead. No problem! The Cache component provides the +:class:`Symfony\\Component\\Cache\\Simple\\Psr6Cache` class for exactly +this use-case:: + + use Symfony\Component\Cache\Adapter\FilesystemAdapter; + use Symfony\Component\Cache\Simple\Psr6Cache; + + // the PSR-6 cache object that you want to use + $psr6Cache = new FilesystemAdapter(); + + // a PSR-16 cache that uses your cache internally! + $psr16Cache = new Psr6Cache($psr6Cache); + + // now use this wherever you want + $githubApiClient = new GitHubApiClient($psr16Cache);