|
| 1 | +.. index:: |
| 2 | + single: Cache Item |
| 3 | + single: Cache Expiration |
| 4 | + single: Cache Exceptions |
| 5 | + |
| 6 | +Cache Items |
| 7 | +=========== |
| 8 | + |
| 9 | +Cache items are the information units stored in the cache as a key/value pair. |
| 10 | +In the Cache component they are represented by the |
| 11 | +:class:`Symfony\\Component\\Cache\\CacheItem` class. |
| 12 | + |
| 13 | +Cache Item Keys and Values |
| 14 | +-------------------------- |
| 15 | + |
| 16 | +The **key** of a cache item is a UTF-8 encoded string which acts as its |
| 17 | +identifier, so it must be unique for each cache pool. You can freely choose the |
| 18 | +keys, but they should only contain letters (A-Z, a-z), numbers (0-9) and the |
| 19 | +``_`` and ``.`` symbols. Other common symbols (such as ``{``, ``}``, ``(``, |
| 20 | +``)``, ``/``, ``\`` and ``@``) are reserved by the PSR-6 standard for future |
| 21 | +uses. |
| 22 | + |
| 23 | +The **value** of a cache item can be any data represented by a type which is |
| 24 | +serializable by PHP, such as basic types (string, integer, float, boolean, null), |
| 25 | +arrays and objects. |
| 26 | + |
| 27 | +Creating Cache Items |
| 28 | +-------------------- |
| 29 | + |
| 30 | +Cache items are created with the ``getItem($key)`` method of the cache pool. The |
| 31 | +argument is the key of the item:: |
| 32 | + |
| 33 | + // $cache pool object was created before |
| 34 | + $numProducts = $cache->getItem('stats.num_products'); |
| 35 | + |
| 36 | +Then, use the :method:`Psr\\Cache\\CacheItemInterface::set` method to set |
| 37 | +the data stored in the cache item:: |
| 38 | + |
| 39 | + // storing a simple integer |
| 40 | + $numProducts->set(4711); |
| 41 | + $cache->save($numProducts); |
| 42 | + |
| 43 | + // storing an array |
| 44 | + $numProducts->set(array( |
| 45 | + 'category1' => 4711, |
| 46 | + 'category2' => 2387, |
| 47 | + )); |
| 48 | + $cache->save($numProducts); |
| 49 | + |
| 50 | +The key and the value of any given cache item can be obtained with the |
| 51 | +corresponding *getter* methods:: |
| 52 | + |
| 53 | + $cacheItem = $cache->getItem('exchange_rate'); |
| 54 | + // ... |
| 55 | + $key = $cacheItem->getKey(); |
| 56 | + $value = $cacheItem->get(); |
| 57 | + |
| 58 | +Cache Item Expiration |
| 59 | +~~~~~~~~~~~~~~~~~~~~~ |
| 60 | + |
| 61 | +By default cache items are stored permanently. In practice, this "permanent |
| 62 | +storage" can vary greatly depending on the type of cache being used, as |
| 63 | +explained in the :doc:`/components/cache/cache_pools` article. |
| 64 | + |
| 65 | +However, in some applications it's common to use cache items with a shorter |
| 66 | +lifespan. Consider for example an application which caches the latest news just |
| 67 | +for one minute. In those cases, use the ``expiresAfter()`` method to set the |
| 68 | +number of seconds to cache the item:: |
| 69 | + |
| 70 | + $latestNews = $cache->getItem('latest_news'); |
| 71 | + $latestNews->expiresAfter(60); // 60 seconds = 1 minute |
| 72 | + |
| 73 | + // this method also accepts \DateInterval instances |
| 74 | + $latestNews->expiresAfter(DateInterval::createFromDateString('1 hour')); |
| 75 | + |
| 76 | +Cache items define another related method called ``expiresAt()`` to set the |
| 77 | +exact date and time when the item will expire:: |
| 78 | + |
| 79 | + $mostPopularNews = $cache->getItem('popular_news'); |
| 80 | + $mostPopularNews->expiresAt(new \DateTime('tomorrow')); |
| 81 | + |
| 82 | +Cache Item Hits and Misses |
| 83 | +-------------------------- |
| 84 | + |
| 85 | +Using a cache mechanism is important to improve the application performance, but |
| 86 | +it should not be required to make the application work. In fact, the PSR-6 |
| 87 | +standard states that caching errors should not result in application failures. |
| 88 | + |
| 89 | +In practice this means that the ``getItem()`` method always returns an object |
| 90 | +which implements the ``Psr\Cache\CacheItemInterface`` interface, even when the |
| 91 | +cache item doesn't exist. Therefore, you don't have to deal with ``null`` return |
| 92 | +values and you can safely store in the cache values such as ``false`` and ``null``. |
| 93 | + |
| 94 | +In order to decide if the returned object is correct or not, caches use the |
| 95 | +concept of hits and misses: |
| 96 | + |
| 97 | +* **Cache Hits** occur when the requested item is found in the cache, its value |
| 98 | + is not corrupted or invalid and it hasn't expired; |
| 99 | +* **Cache Misses** are the opposite of hits, so they occur when the item is not |
| 100 | + found in the cache, its value is corrupted or invalid for any reason or the |
| 101 | + item has expired. |
| 102 | + |
| 103 | +Cache item objects define a boolean ``isHit()`` method which returns ``true`` |
| 104 | +for cache hits:: |
| 105 | + |
| 106 | + $latestNews = $cache->getItem('latest_news'); |
| 107 | + |
| 108 | + if (!$latestNews->isHit()) { |
| 109 | + // do some heavy computation |
| 110 | + $news = ...; |
| 111 | + $cache->save($latestNews->set($news)); |
| 112 | + } else { |
| 113 | + $news = $latestNews->get(); |
| 114 | + } |
0 commit comments