How do I programmatically set cache age?

Question

Drupal 8:

I have the code for a block successfully doing its work and returning it. The block is called "RacerProfile" and it dumps all its content into variable "$pageContent". At the very end it returns the #markup. Ok. Now how do I tell this to invalidate every six hours?

/**
 * Provides a 'Racer Profile' Block
 *
 * @Block(
 *   id = "racer_profile",
 *   admin_label = @Translation("Slider v1 block")
 * )
 */
class RacerProfile extends BlockBase {
  /**
   * {@inheritdoc}
   */
  public function build() 
    {
    // does all the work to make $pageContent via non-drupal database queries 
    return array('#markup' => $this->t($pageContent),  );
    }
 }

In other Drupal answers, I've seen "D8 has cache tags and contexts that will automatically invalidate the block if something changes." Ok, my code is checking a second database. There's no way for Drupal to know what's changing over there. (Without checking, obviously.) So how do I add cache tags with specified timeouts? I can't find examples.

Notes:

-Obviously, this is not related to the Maximum Cache age within the admin area of Configuration > Performance > Caching > Page cache maximum age. I don't want this to apply to the entire site, just this block.

-Obviously, this is not related to settings.php in any way either, since again I don't want to have this apply to the entire site, and the various modules will have different timeout requirements.

-The traffic for the site is relatively low volume, so if rendering a thing four times a day even it only needs to be done once a day isn't a problem. Every six hours means that it's changed before people wake up across four time zones. Mostly. ;)

-(edit addition) The block needs to have its cache controlled for anonymous users.

Answer 1

This is all done from the render array itself. The nitty gritty details are documented in Cacheability of render arrays.

In your case, you need to do something like

return [
  '#markup' => $this->t($pageContent),
  '#cache' => [
    'max-age' => 86400, // one day in seconds
  ],
];

This uses the #cache entry for the render array, and sets the max-age to be one day. This is where you would also add in your cache contexts.

As a side note, try to avoid using '#markup'. Use themeable elements, either though code or Twig.

Answer 2

For cache settings of the dynamic cache see the answer from @MPD .

For the whole page you can set a global max-age in admin/config/development/performance.

The parameter is "Page cache maximum age". This is a bit misleading, because the Internal Page Cache does not respect this parameter *), but only puts this value in the response header for reverse proxies and browser caches.

For a high traffic site I would recommend to disable the Internal Page Cache (but keep the dynamic cache!) and use varnish, which will respect the max-age header and provides fine tuning for further handling of the headers.

Edit:

*) The reason for this behavior is, that Internal Page Cache uses Cache::PERMANENT, if the expire date is in the past:

$date = $response->getExpires()->getTimestamp();
$expire = ($date > time()) ? $date : Cache::PERMANENT;

And this expire date is set to "9-Nov-1978" by FinishResponseSubscriber:

 /**
   * Disable caching in ancient browsers and for HTTP/1.0 proxies and clients.
   *
   * HTTP/1.0 proxies do not support the Vary header, so prevent any caching by
   * sending an Expires date in the past. HTTP/1.1 clients ignore the Expires
   * header if a Cache-Control: max-age= directive is specified (see RFC 2616,
   * section 14.9.3).
   *
   * @param \Symfony\Component\HttpFoundation\Response $response
   *   A response object.
   */
  protected function setExpiresNoCache(Response $response) {
    $response->setExpires(\DateTime::createFromFormat('j-M-Y H:i:s T', '19-Nov-1978 05:00:00 UTC'));
  }

Answer 3

Confirming with previous comments in the thread that the best (if not easiest) way to make Drupal's Internal Page Cache "respect" the cache lifetime is to create an Event Subscriber that modifies the FinishResponseSubscriber shown above.

See boilerplate code for doing so at Anonymous user cache control