Drupal 8 Block Cache

In case you've had trouble tracking it down (I did), the approach to caching custom blocks is different in Drupal 8 than in Drupal 7. In Drupal 8 all renderable arrays are cacheable – including, of course, those returned by custom blocks.

The new and much-improved Cache API in Drupal 8 provides a sophisticated approach to caching all things renderable–whether pages, entities or, for our case, blocks. Whereas in Drupal 7 default cache settings were returned along with other block settings in "hook_block_info()", Drupal 8 allows developers to manage cache behavior for blocks directly in the render array returned by the block object's "build()" method.

In Drupal 7, caching a block by role looks this:

function mymodule_block_info() {
  $blocks = array();
  $blocks['mymodule_example_block'] = array(
    'info' => t('Block title'),
    // Block caching options (per role, per user, etc.)
    // DRUPAL_CACHE_PER_ROLE is the default.
    'cache' => DRUPAL_CACHE_PER_ROLE,
  return $blocks;

In Drupal 8, cache settings are manipulated directly in renderable arrays returned by (among other things) a block's build() method:

class MyCustomBlock extends BlockBase {
  public function build() {
    return array(
      '#markup' => $this->t('My custom block content'),
      '#cache' => array(
        'contexts' => array('user.roles'),

Available parameters for manipulating cache settings include 'keys', 'contexts', 'tags', 'max-age' and 'bin'. Detailed documentation about cache management in Drupal 8 is available on Drupal.org.

Beyond implications for caching blocks (which had me scouring Google when first writing custom block plugins for Drupal 8) there are huge implications for caching everything. In Drupal 8, cache behavior needs to be a consideration when rendering absolutely anything via the render API. More on that on Drupal.org.

Code Drupal 8 Drupal Drupal Planet

Read This Next