New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Added the documentation for the Cache component #6515

Closed
wants to merge 23 commits into
base: master
from

Conversation

Projects
None yet
9 participants
@javiereguiluz
Member

javiereguiluz commented Apr 25, 2016

This fixes #6171.

This is WIP because there's more documentation to come ... but you can already review the proposed documentation. Thanks!

Now you can create, retrieve, updated and delete items using this cache pool::

// create a new item by trying to get it from the cache
$numProducts = $cache->getItem('stats.num_products');

This comment has been minimized.

@teohhanhui

teohhanhui Apr 25, 2016

Contributor

The variable naming is confusing... What about $numProductsCacheItem?

This comment has been minimized.

@javiereguiluz

javiereguiluz Apr 25, 2016

Member

Nice catch. I refactored this example before and forgot to update that part. It's updated now. Thanks.

javiereguiluz added some commits Apr 25, 2016

@javiereguiluz

This comment has been minimized.

Member

javiereguiluz commented Apr 25, 2016

Update the docs for the cache items has been added. Next chapter: cache pools.

javiereguiluz added some commits Apr 25, 2016

@javiereguiluz

This comment has been minimized.

Member

javiereguiluz commented Apr 26, 2016

Update in 599ed0a I've added an article about "Cache Pools". I have two questions:

  1. I don't know how to create cache pools. Please, someone share a snippet with me.

  2. What happens when you remove a cache item that doesn't exist? Do you get true as result?

Thanks!

@teohhanhui

This comment has been minimized.

Contributor

teohhanhui commented Apr 26, 2016

It's also possible to override cache pools used by various Symfony services: #6171 (comment)

@javiereguiluz

This comment has been minimized.

Member

javiereguiluz commented Apr 26, 2016

@teohhanhui thanks ... but right now we are documenting the component. The integration with Symfony (and FrameworkBundle) will be documented later. So the question remains: how to create a cache pool with the Cache component?

@teohhanhui

This comment has been minimized.

Contributor

teohhanhui commented Apr 26, 2016

@javiereguiluz:

What happens when you remove a cache item that doesn't exist? Do you get true as result?

From PSR-6:

If a Calling Library requests that one or more Items be deleted, or that a pool be cleared, it MUST NOT be considered an error condition if the specified key does not exist.

@teohhanhui

This comment has been minimized.

Contributor

teohhanhui commented Apr 26, 2016

If by "cache pool" you mean Psr\Cache\CacheItemPoolInterface, then just instantiate the adapters...

On the other hand, cache pools as per the cache.pool DI tag are services processed by the compiler pass. They're conceptual. The actual instance is still one of the adapters.

@javiereguiluz

This comment has been minimized.

Member

javiereguiluz commented Apr 26, 2016

Update: finished the first version of the doc for the Cache component.

@tgalopin @nicolas-grekas when you have some time, please review the docs of this PR and tell me what you think. After that, I'll write the docs about integrating Cache in Symfony framework. Thanks!

Cache Items
===========

Cache items are each one of the information units stored in the cache as a

This comment has been minimized.

@nicolas-grekas

nicolas-grekas Apr 26, 2016

Member

Cache items are each one of the information units (or looks strange to me)

The **key** of a cache item is a UTF-8 encoded string which acts as its
identifier, so it must be unique for each cache pool. The PSR-6 standard limits
the key length to 64 characters, but Symfony allows to use longer keys (they are
encoded internally to reduce their size).

This comment has been minimized.

@nicolas-grekas

nicolas-grekas Apr 26, 2016

Member

They are not encoded for all adapters but still the length is not limited. I suggest removing these brackets.

This comment has been minimized.

@teohhanhui

teohhanhui Apr 27, 2016

Contributor

I'd advocate for keeping to 64 characters anyway, for interoperability (the whole point of PSR interfaces...)

This comment has been minimized.

@javiereguiluz

javiereguiluz Apr 27, 2016

Member

If Symfony follows this 64-char limit internally and it doesn't enforce it externally, I think we should remove this information.

This comment has been minimized.

@teohhanhui

teohhanhui Apr 28, 2016

Contributor

It does not matter what Symfony Cache does internally. The interface only guarantees that keys up to 64 characters will work. Say, the user swap out Symfony Cache for another PSR-6 cache, things might break if they go over that limit. And we should encourage users to stay within the limit - warn them of the risk of doing otherwise.

the key length to 64 characters, but Symfony allows to use longer keys (they are
encoded internally to reduce their size).

You can freely chose the keys, but they can only contain letters (A-Z, a-z),

This comment has been minimized.

@nicolas-grekas

nicolas-grekas Apr 26, 2016

Member

they can -> they should? (because we allow any other non-reserved chars)

This comment has been minimized.

@teohhanhui

teohhanhui Apr 27, 2016

Contributor

chose -> choose


You can freely chose the keys, but they can only contain letters (A-Z, a-z),
numbers (0-9) and the ``_`` and ``.`` symbols. Other common symbols (such as
``{``, ``}``, ``(``, ``)``, ``/``, ``\`` and ``@``) are reserved for future uses.

This comment has been minimized.

@nicolas-grekas

This comment has been minimized.

@teohhanhui

teohhanhui Apr 27, 2016

Contributor

Can we link to the relevant sections in PSR-6?


The **value** of a cache item can be any data represented by a type which is
serializable by PHP, such as basic types (strings, integers, floats, boolean,
nulls), arrays and objects.

This comment has been minimized.

@nicolas-grekas

nicolas-grekas Apr 26, 2016

Member

nulls (not s)

argument is the key of the item::

// $cache pool object was created before
$cachedNumProducts = $cache->getItem('stats.num_products');

This comment has been minimized.

@nicolas-grekas

nicolas-grekas Apr 26, 2016

Member

$pool->getItem(...?

This comment has been minimized.

@HeahDude

HeahDude Apr 27, 2016

Member

Does num stand for a total quantity or an identifier? In case of quantity I'd name it 'stats.count_products'.

~~~~~~~~~~~~~~~~~~~~~

By default cache items are stored "permanently", which in practice means "as long
as allowed by the cache implementation used".

This comment has been minimized.

@nicolas-grekas

nicolas-grekas Apr 26, 2016

Member

as long as the cache pool is not cleared also?

This comment has been minimized.

@teohhanhui

teohhanhui Apr 27, 2016

Contributor

I think that's already understood. This is talking about expiration. Clearing is a different matter.


In practice this means that the ``getItem()`` method always returns an object
which implements the ``Psr\Cache\CacheItemInterface`` interface, even when the
cache item doesn't exist. Therefore, you don't have to deal with ``null`` values.

This comment has been minimized.

@nicolas-grekas

nicolas-grekas Apr 26, 2016

Member

This allows caching e.g. null or false values?

for cache hits::

$latestNews = $cache->getItem('latest_news');
$latestNews->expiresAfter(60);

This comment has been minimized.

@nicolas-grekas

nicolas-grekas Apr 26, 2016

Member

not sure this example is the good one here, i'd suggest something like the following, which is the canonical snippet when dealing with arbitrary cached values to me:

$latestNews = $cache->getItem('latest_news');

if (!$latestNews->isHit()) {
   $value = //... do some heavy computation
    $pool->save($latestNews->set($value));
} else {
    $value = $latestNews->get();
}
@unexge

This comment has been minimized.

unexge commented May 22, 2016

maybe this case can be added as note to;

$cache = new FilesystemAdapter('foo', 3600);

$cacheItem = $cache->getItem('bar');

$cacheItem->set('baz');

// the cacheItem will not expire after 3600 seconds, it'll live forever
$cache->save($cacheItem);

// you need to call expiresAfter or expiresAt with null parameter if you want to use defaultLifetime
$cacheItem->expiresAfter(null);

// the cacheItem will expire after 3600 seconds
$cache->save($cacheItem);
.. note::

In Symfony applications this component is integrated (and enabled by
default) through the FrameworkBundle.

This comment has been minimized.

@wouterj

wouterj Jun 14, 2016

Member

we don't have this note for other components as well, what about removing it here?

can define as many pools as needed.
* **Adapter**, it implements the actual caching mechanism to store the
information in the filesystem, in a database, etc. The component provides
several ready to use adapters for common caching backends (Redis, APCu, etc.)

This comment has been minimized.

@wouterj

wouterj Jun 14, 2016

Member

let's use a definition list here:

**Item**
    A single unit [...]
**Pool**
    A logical repository [...]
**Adapter**
    A [...]

This comment has been minimized.

@wouterj

wouterj Jun 14, 2016

Member

Adapters are pools, should we document that as well?

This comment has been minimized.

@teohhanhui

teohhanhui Jun 14, 2016

Contributor

It should be the other way round, i.e. pools (a concept) are actually adapters, but not all adapters are pools.

This comment has been minimized.

@teohhanhui

teohhanhui Jun 14, 2016

Contributor

Oh wait... Here we're not talking about the "pools" concept introduced in the FrameworkBundle. Overloaded terms are far too confusing...

// retrieve the cache item
$numProducts = $cache->getItem('stats.num_products');
// check whether the item exists in the cache
$isCached = $numProducts->isHit();

This comment has been minimized.

@wouterj

wouterj Jun 14, 2016

Member

we don't check anything here, we just simply store a boolean. What about:

// retrieve the cache item
$numProducts = $cache->getItem('stats.num_products');
if (!$numProducts->isHit()) {
    // ... item does not exists in the cache
}
// retrieve the value stored by the item
$total = $numProducts->get();

// remove the cache item
$cache->deleteItem('stats.num_products');

This comment has been minimized.

@wouterj

wouterj Jun 14, 2016

Member

let's add links to the other sections in a new section at the end of the introduction

Cache Items
===========

Cache items are each of the information units stored in the cache as a key/value

This comment has been minimized.

@wouterj

wouterj Jun 14, 2016

Member

I think "each of" can be removed?

// $cache pool object was created before
$numProducts = $cache->getItem('stats.num_products');

Then, use the ``set($value)`` method to set the data stored in the cache item::

This comment has been minimized.

@wouterj

wouterj Jun 14, 2016

Member

let's use an API link here

.. note::

Creating a cache item and setting its value is not enough to save it in the
cache. You must execute the ``save($cacheItem)`` method explicitly on the

This comment has been minimized.

@wouterj

wouterj Jun 14, 2016

Member

we don't put arguments in the parenthesis when refering to methods

--------------------------

Using a cache mechanism is important to improve the application performance, but
it should not be required to make the application work. In fact, the Cache

This comment has been minimized.

@wouterj

wouterj Jun 14, 2016

Member

What's the "cache standard"?

$latestNews = $cache->getItem('latest_news');

if (!$latestNews->isHit()) {
$news = //... do some heavy computation

This comment has been minimized.

@wouterj

wouterj Jun 14, 2016

Member

the doc standard is:

// do some heavy computation
$news = ...;
--------------------

Cache Pools are created through the **cache adapters**, which are classes that
implement the :class:`Psr\\Cache\\CacheItemPoolInterface` interface. This

This comment has been minimized.

@wouterj

wouterj Jun 14, 2016

Member

"which" refers to "cache adapters", these implement AdapterInterface (which extends CacheItemPoolInterface).

This comment has been minimized.

@javiereguiluz

javiereguiluz Jun 14, 2016

Member

I don't understand this comment. Please tell me how to reword this paragraph:

Cache Pools are created through the **cache adapters**, which are classes that
implement the :class:`Psr\\Cache\\CacheItemPoolInterface` interface. This
component provides several adapters ready to use in your applications.

Thanks.

This comment has been minimized.

@wouterj

wouterj Jun 17, 2016

Member

With the current situation, it seems like I need to implement CacheItemPoolInterface when I want to create a custom adapter. However, I have to to implement AdapterInterface (unless I'm wrong of course).

This comment has been minimized.

@nicolas-grekas

nicolas-grekas Jun 17, 2016

Member

true for symfony derivated adapters (AdapterInterface extends CacheItemPoolInterface)


$cache = new ChainAdapter(array($apcCache, $fileCache));

when an item is not found in the first adapters but is found in the next ones,

This comment has been minimized.

@wouterj

wouterj Jun 14, 2016

Member

"When [...]"

default) and the default lifetime (``0`` by default).

Another use case for this adapter is to get statistics and metrics about the
cache hits and misses thanks to the ``getHits()`` and ``getMisses()`` methods.

This comment has been minimized.

@wouterj

wouterj Jun 14, 2016

Member

"thanks to [...]" can be removed imo

Saving Cache Items
------------------

The most common method to save cache items is ``save($item)``, which stores the

This comment has been minimized.

@wouterj

wouterj Jun 14, 2016

Member

let's use API links (same below for the other methods)

@nicolas-grekas

This comment has been minimized.

Member

nicolas-grekas commented Jun 17, 2016

time to merge this one, features for 3.2 are coming :)

.. note::

Creating a cache item and setting its value is not enough to save it in the
cache. You must execute the ``save()`` method explicitly on the cache pool.

This comment has been minimized.

@xabbuh

xabbuh Jun 20, 2016

Member

Why not showing this directly in the example above?

This comment has been minimized.

@xabbuh

xabbuh Jun 22, 2016

Member

@javiereguiluz What do you think about this? Besides this to me this one is ready to be merged.

This comment has been minimized.

@javiereguiluz

javiereguiluz Jun 26, 2016

Member

I've implemented this change.

@eXtreme

This comment has been minimized.

Contributor

eXtreme commented Jun 21, 2016

Finally merging something would be great because searching through these PRs, tests and DI config is not very helpful in understanding how to set it up correctly. AFAIR there even wasn't any "New in Symfony" article about this PSR6 cache.

@javiereguiluz

This comment has been minimized.

Member

javiereguiluz commented Jun 21, 2016

@eXtreme you are right. And the "New in Sf" article about the Cache is pending too.

@wouterj

This comment has been minimized.

Member

wouterj commented Jun 26, 2016

Status: reviewed 👍

@javiereguiluz

This comment has been minimized.

Member

javiereguiluz commented Jun 26, 2016

I've made all the requested changes. I beg Doc Maintainers to merge this before someone else asks for more changes 😄 Thanks!

xabbuh added a commit that referenced this pull request Jun 30, 2016

feature #6515 Added the documentation for the Cache component (javier…
…eguiluz)

This PR was submitted for the master branch but it was merged into the 3.1 branch instead (closes #6515).

Discussion
----------

Added the documentation for the Cache component

This fixes #6171.

This is WIP because there's more documentation to come ... but you can already review the proposed documentation. Thanks!

Commits
-------

6ddde65 Added the documentation for the Cache component
@xabbuh

This comment has been minimized.

Member

xabbuh commented Jun 30, 2016

It took us some time. But now we are there. Thank you for writing the documentation, Javier!

@xabbuh xabbuh closed this Jun 30, 2016

@javiereguiluz javiereguiluz added the Cache label Jan 11, 2017

@javiereguiluz javiereguiluz deleted the javiereguiluz:cache_component branch May 24, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment