Added the documentation for the Cache component

[javiereguiluz]

This fixes #6171.

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

[teohhanhui]

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

[javiereguiluz]

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

[javiereguiluz]

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

[javiereguiluz]

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 is how to create cache pools with FrameworkBundle: https://github.com/nicolas-grekas/symfony/blob/84b48de2998524558c1b027763f9af0dbc29f298/src/Symfony/Bundle/FrameworkBundle/Tests/DependencyInjection/Fixtures/yml/cache.yml

[teohhanhui]

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

[javiereguiluz]

@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]

@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]

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]

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!

[nicolas-grekas]

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

[unexge]

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);

[wouterj]

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

[nicolas-grekas]

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

[xabbuh]

Why not showing this directly in the example above?

[xabbuh]

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

[javiereguiluz]

I've implemented this change.

[eXtreme]

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]

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

[wouterj]

Status: reviewed 👍

[javiereguiluz]

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

[xabbuh]

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