Cache documentation lacking

Thanks for making an issue! You could have also repurposed your original issue, but that is fine.

So, let's see what might need documenting, and see if/where.

a) On that other issue, you found that if you added something to a render array without any cache information, it was automatically cached. We do have some documentation caching in render arrays in the Render API topic:
https://api.drupal.org/api/drupal/core!lib!Drupal!Core!Render!theme.api....
and I think that what is there is accurate, but limited. That is probably OK.

In your case you might have thought it didn't apply because you didn't put #cache or anything like that in your render array, but since it was part of node preprocessing, the node as a whole had cache tags so the whole thing was going to be cached.

So assuming you knew it applied, I think reading the short descriptions you'd figure out you needed a cache context probably? Hopefully...

b) Either that, or you'd figure you needed more information. So that documentation page points to
https://www.drupal.org/developing/api/8/render/arrays/cacheability
for more information. That page explains in more detail about cache stuff, and then points you to
https://www.drupal.org/developing/api/8/cache/contexts
for details on cache contexts (which again I think you'd hopefully realize you'd need to learn more about).

Hm... That page could probably use some love. As documentation goes, I didn't find it all that easy to use for practical purposes.

c) The other starting point on api.drupal.org, if you knew you had cache issues, would likely be
https://api.drupal.org/api/drupal/core!core.api.php/group/cache/8
That page also has a short section on cache contexts, also pointing to https://www.drupal.org/developing/api/8/cache/contexts for more details.

So. My feeling is that we need to make
https://www.drupal.org/developing/api/8/cache/contexts
more useful to someone in your situation. It looks like from your report that you came to the same conclusion, that this page needs to be more useful/practical to the developer.

Anything else you think we need to improve? Any thoughts?

I also have problems with the documentation.

How can i set a variable in the function theme_preprocess_page() that changes when a cookie changes?

for example:

$variables['testvariable'] = $_COOKIE['testcookie'];
$variables['#cache']['contexts'][] = 'cookies:testcookie';

in page.html.twig
{{ testvariable }}

or

$variables['testvariable'] = [
    'value' => $_COOKIE['testcookie'],
    '#cache' => [
      'contexts' => 'cookies:testcookie',
    ],
  ];

in page.html.twig
{{ testvariable.value }}

I know I need cache tags, but which ones? I also set the max-age to 0, but nothing works. The value doesn't change for anonymous users.

I'm stuck in the same problem. Did you figure out how to solve the cookie/contexts problem ?

I also change the templates variables depending on a specific cookie value like :

function hook_preprocess(&$variables, $hook) {
    $gamma_cookie = \Drupal::request()->cookies->get('gamma_rol');
    $variables['gamma_rol'] = $gamma_cookie;
    $variables['#cache']['contexts'][] = 'cookies:gamma_rol';
}

But is not working for anonymous user when the cache is activated.
Any help ?

thank you

One more person here, I think with the same problem. Is this PEBKAC?

Aim:

I want to invalidate the anonymous user's (log-in) page cache after, say, 120sec,

Method

1. In function theme_preprocess_page() I added

\Drupal::logger('custom_userlogin')->debug(__METHOD__);
$uid  = \Drupal::currentUser()->id();
if ( !$uid || $uid <= 0) {
  $variables['#cache']['max-age'] = 120;
  $variables['last_cached'] = date("Y-m-d H:i:s");
}

Then, in page.html.twig I insert the following little test.
Last cached: {{ last_cached }}

2. As 'admin' in Firefox I clear the Cache,
3. As anonymous user in Chrome I load the site, using XDEBUG to trace it.
4. Capture starting values using XDEBUG

Starting values

$variables['#cache'] ['contexts'] = ["user.permissions"];
$variables['#cache']['max-age'] = 120;
$variables['last_cached'] = "2017-08-30 14:16:42";

5. Wait 2 min and refresh the page (CTRL + F5) from the server.
6. Wait another 2 min and do it again

Expected

The rendered 'last_cached' value changes to a more recent string each time I hard refresh the page after more than 2 minutes.
The admin user's log detects each new access into the logic of theme_preprocess_page().

Found

It does not change. Nor does the admin user's recent log messages detect any new visit to theme_preprocess_page().

Conclusion

1. Subsequent hard refreshes more than 2 min later are served using the same long-term cache copy,
2. the logic does not again traverse theme_preprocess_page() until the cache is cleared.

Stumped. Where are the cache instructions being overruled?

More

[edited]
I thought I had an answer but alas I did not.
Still stuck.
I would love it if i could make the Internal Page Cache respect the max_age value set via the admin Performance page!

This, it seems is a known issue.

See

1. Bubbling of elements' max-age to the page's headers and the page cache
2. Time based cache does not work as expected for anonymous users

Thank you for creating this issue to improve Drupal.

We are working to decide if this task is still relevant to a currently supported version of Drupal. There hasn't been any discussion here for over 8 years which suggests that this has either been implemented or is no longer relevant. Your thoughts on this will allow a decision to be made.

Since we need more information to move forward with this issue, the status is now Postponed (maintainer needs more info). If we don't receive additional information to help with the issue, it may be closed after three months.

Thanks!