Block Cache API is removed; blocks now use standard caching patterns

Motivation for the change

Blocks having their own caching system is obsolete as of #918808: Standardize block cache as a drupal_render() #cache Standardize block cache as a drupal_render() #cache. They effectively are using render caching (#cache).

Blocks now set the appropriate cache tags, so that they can use the same render cache invalidation mechanism as everything else.

Code examples

Prior to this change

From BlockBase

public function defaultConfiguration() {
  return array(
    'cache' => DRUPAL_CACHE_PER_PAGE | DRUPAL_CACHE_PER_ROLE,
    'block_mode' => "all pages",
  );
}

Current practice

Block caching configuration defaults are defined in the BlockBase class.

<?php

abstract class BlockBase extends PluginBase implements BlockPluginInterface {
  ...
  /**
   * Returns generic default configuration for block plugins.
   *
   * @return array
   *   An associative array with the default configuration.
   */
  protected function baseConfigurationDefaults() {
    return array(
      'label' => '',
      'module' => $this->pluginDefinition['module'],
      'label_display' => BlockInterface::BLOCK_LABEL_VISIBLE,
      'cache' => array(
        'max_age' => 0,
      ),
    );
  }
  …
}

To override the configuration defaults in a block instance (a placed block), take one of the following actions:

• Change the cache setting for the placed block through the UI
• Manipulate the corresponding configuration YML file (which is what the UI is doing).

When creating a new block, defaults may be specified that override the BlockBase defaults. Implement any of the following methods to override the defaults.

• defaultConfiguration()
• getCacheContexts()
• getCacheTags()
• getCacheMaxAge()

API changes

• BlockPluginInterface now extends CacheableDependencyInterface — so each block must now declare whether they are cacheable, and if so, define how they are cachable. See the change notice for CacheableDependencyInterface. (Note: BlockBase takes away all this work if you don’t want to deal with this.)
• drupal_render_cache_by_query() is replaced with Cache::keyFromQuery().

New methods

Blocks that subclass BlockBase automatically get a cache settings UI that allows the user to configure a block’s maximum caching age. Note that cache contexts, tags and max-age of the contents of the block are bubbled automatically, and are thus merged with the cache contexts, tags and max-age of the block itself (which you could consider the "intrinsic" cacheability metadata).

Example fromSystemMenuBlock:

  /**
   * {@inheritdoc}
   */
  public function getCacheContexts() {
    $menu_name = $this->getDerivativeId();
    return [
      'route.menu_active_trails:' . $menu_name,
    ];
  }

D7 Block API constants

The following block cache constants have been replaced with the combination of the cache.max_age and ::getCacheContexts() return values (or bubbled cache contexts) on blocks:

DRUPAL_NO_CACHE (equivalent: cache.max_age = 0)
DRUPAL_CACHE_CUSTOM (equivalent: cache.max_age = 0 + Cache::keyFromQuery())
DRUPAL_CACHE_PER_ROLE (equivalent: cache.max_age >0 + user.roles)
DRUPAL_CACHE_PER_USER (equivalent: cache.max_age >0 + user)
DRUPAL_CACHE_PER_PAGE (equivalent: cache.max_age >0 + url)
DRUPAL_CACHE_GLOBAL (equivalent: cache.max_age >0, no cache contexts)

New: cache contexts

See https://www.drupal.org/developing/api/8/cache/contexts.