Problem/Motivation

Spin-off from #3582087: Consolidate high level Drupal core documentation in markdown files and publish them via gitlab pages and #3463660: [policy, no patch] Document high-level API concepts in an easier format.

We should try to produce markdown documentation for one subsystem first, I suggested cache API in the other issue partly because it's one I work on a lot, but also it's fairly low level while also being relatively large. This should give us a template which can be applied to other things (routing, request processing, config, routing, plugins).

Cache docs notes via the other issue:

Existing docs are in these two places:

https://api.drupal.org/api/drupal/core%21core.api.php/group/cache/11.x
https://www.drupal.org/docs/8/api/cache-api/cache-api

This would move to a new docs/cache.md file.

Symfony and Laravel pages for comparison:
https://symfony.com/doc/current/components/cache.html
https://laravel.com/docs/11.x/cache

Steps to reproduce

Proposed resolution

Remaining tasks

User interface changes

Introduced terminology

API changes

Data model changes

Release notes snippet

Issue fork drupal-3582253

Command icon Show commands

Start within a Git clone of the project using the version control instructions.

Or, if you do not have SSH keys set up on git.drupalcode.org:

About issue forks

Comments

catch created an issue. See original summary.

catch’s picture

catch
he/him
Primary language English
commented

Quick draft of a suggested structure. The content for each section can probably mostly be c&ped from the existing docs.

-0. Very short intro/index at the top with quick links to the later sections, could maybe be an auto-generated index from the sections.

1. Object caching

Cache backends and basic operations
Cache bins + swappability (mention database/apcu in core + redis/memcache in contrib)
Cache IDs
Cache tags - setting them and invalidating them.
Expires

memory + LRU memory,

Chained / Chained fast backend.

2. Variation cache

Introduce cache contexts, abstract explanation but also descriptions of the main ones in core + links.

CacheableDependencyInterface/CacheableMetadata as a transport mechanism for tags + contexts + max age

Cross reference to https://www.drupal.org/docs/8/api/cache-api/access-checkers-cacheability (markdown version when it exists, access.md) - but I think the access-specific stuff should be in the Access api documentation, since that's where it's important to present it to people, when they're trying to implement access.

3. Render caching

[this should probably link to the render API docs, since it should probably be introduced in the context of #cache + #pre_render, what it means to have #cache['cid'] vs. not, #lazy_builder and #create_placeholder which are more render API concepts.] Explain that entity rendering, blocks, views etc. implement this out of the box.

4.

Dynamic page cache

Internal page cache and reverse proxy caching of HTML

kristiaanvandeneynde’s picture

kristiaanvandeneynde
Primary language Dutch
Location Antwerp, Belgium
commented

I would keep the cacheable metadata topics closer together. Only explaining cache contexts when talking about VC seems fine at first, but then you lose the opportunity to say: These concepts all belong together.

I'd rather explain the possible values of cacheable metadata and then refer to the VC section further below for a more detailed explanation.

Example:

1. Object caching
- Cache backends and basic operations, refer to cacheable metadata section below for "expire" and "tags"
- Cache bins + swappability (mention database/apcu in core + redis/memcache in contrib)
- Cache IDs, can internally be influenced by cache contexts, refer to cacheable metadata and VC sections
- Memory + LRU memory
- Chained / Chained fast backend

2. Cacheable metadata
- Cache tags - setting them and invalidating them.
- Max-age and how that affects Expires
- Cache contexts
--- Explain they represent variations
--- What they look like
--- Refer to VC section to explain how they can sometimes automatically be ignored (optimized away)

3. VariationCache
- What it is
- Descriptions of the main ones in core + links.
- Internals:
--- How it stores with varying CIDs
--- How it optimizes
--- Cache redirects (how a whole chain can be followed)

4. RenderCache
5. DPC
catch’s picture

catch
he/him
Primary language English
commented

#3 sounds good.

Also I didn't put any reasoning for the initial outline, but my idea for this structure was to try to put concepts that people like likely to deal with in the cache API directly first, and which they're more likely to be familiar with from other frameworks - i.e. caching their own stuff in the object cache.

I'm not aware of equivalents of cache contexts/variation cache/dynamic page cache in any other framework anywhere. Other frameworks barely support cache tags and even those tend not to be complete implementations.

Then the higher level concepts later, which you're most likely to encounter via the render and access APIs rather than directly, since implementing variation or render caching from scratch is very rare, they're more things you need to know about when using render arrays or doing access checks for which caching overall is already implemented.

And #3 does this better than my initial outline did by pushing the cacheable metadata stuff later.

quietone made their first commit to this issue’s fork.

quietone opened merge request !17324

quietone’s picture

quietone commented

The MR has markdown for the existing handbook pages and the Caching page from api.d.o. Hopefully, that is all the information and can now be improved as needed. The destination of links hasn't changed but it seems better to fix links when the docs are in better shape.

kristiaanvandeneynde’s picture

kristiaanvandeneynde
Primary language Dutch
Location Antwerp, Belgium
commented
Status: Active » Needs work

Left some comments.

I would ideally like to avoid the following:

  • Anything that mentions a specific version of Drupal
  • Anything that implies a specific version of Drupal, such as the full hierarchy of cache contexts
  • Anything that explains the history behind something, unless it is absolutely necessary to answer a question that would otherwise keep getting asked

The first two items are imperative to keeping these docs current and maintainable. Otherwise it will become a burden to think of them whenever we make a low-impact change or they will become stale rather quickly.

quietone’s picture

quietone commented
Related issues: +#2589573: Cache documentation lacking
abenbow’s picture

abenbow
He/Him/His
Primary language English
commented

I've also done a quick review of the proposed changes and made some recommendations based on some of the feedback that @kristiaanvandeneynde left, hopefully it's helpful for patching up some of these changes.