[Twig] [TwigBundle] Describe the new behaviour of twig.cache config

[Okhoshi]

Update the description of the twig.cache config to follow the changes implemented in symfony/symfony#54384.

Fixes #20948

cc @alexandre-daubois

[javiereguiluz]

Thanks Quentin for this contribution!

I did some minor rewords while merging, but I left your core contribution intact.

---

I find the new docs a bit confusing so I'm asking something to you.

Is the following current explanation:

When set to ``true``, the cache is stored in ``%kernel.cache_dir%/twig`` by default.
However, if ``auto_reload`` is disabled and ``%kernel.build_dir%`` differs from
``%kernel.cache_dir%``, the cache will be stored in ``%kernel.build_dir%/twig`` instead.

Equivalent to this simplified version?

When set to ``true``, the cache is stored in ``%kernel.cache_dir%/twig`` by default.
However, if ``auto_reload`` is disabled the cache will be stored in
``%kernel.build_dir%/twig`` instead.

I mean:

• If auto_reload is disabled:
  • If build_dir and cache_dir are different, then build_dir is used
  • If build_dir and cache_dir are the same, then cache_dir is used. BUT, if they are the same, we're using build_dir
  • So, we always use build_dir when auto_reload is disabled, right?

Maybe I'm missing something here.

[Okhoshi]

@javiereguiluz It's indeed a bit confusing, because the setup is a bit more convoluted, but for the sake of simplicity, not all the details are described in the doc.

There's actually a slight difference when the cache is set to build_dir or cache_dir (other than the directory itself).
If build_dir is used, we construct a two layers cache with a read-only layer pointing to build_dir and a read/write opportunistic cache pointing to cache_dir.
If cache_dir is used, we set up a simple one-layer cache on cache_dir.

Hence why the distinction, even if you are actually right with the simplified version.

Happy to discuss any improvements we can make on the doc for this 👍

[javiereguiluz]

Thanks for the detailed explanation 🙏 I think you are right that it's better to not mention all these internal details in the docs.

Also, let's wait until Symfony uses build_dir for everything and it's "fully read-only" to see if we can tweak many docs at once related to that if we think it's needed.