Breadcrumbs are now passed using a value object with cacheability metadata instead of an array

To make the breadcrumbs block cacheable, the array of breadcrumb links has been replaced by a breadcrumb value object: \Drupal\Core\Breadcrumb\Breadcrumb. This class simply extends \Drupal\Core\Cache\CacheableMetadata (which is a value object for passing cacheability metadata), and on top of that is also capable of containing an array of \Drupal\Core\Link objects that represent the breadcrumb links.

Due to this there are two API changes: one BreadcrumbBuilderInterface::build() must now return this Breadcrumb value object and hook_system_breadcrumb_alter() now receives it.

\Drupal\Core\Breadcrumb\BreadcrumbBuilderInterface

The examples how the changed interface is implemented are taken from BookBreadcrumbBuilder.

Before

BreadcrumbBuilderInterface::build() returns an array of breadcrumb links.

...
class BookBreadcrumbBuilder implements BreadcrumbBuilderInterface {
  ...
  public function build(RouteMatchInterface $route_match) {
    // Prepare array $links.
    ...
    // Return the array.
    return $links;
  }
  ...
}

After

BreadcrumbBuilderInterface::build() returns an instance of Breadcrumb.

...
use Drupal\Core\Breadcrumb\Breadcrumb;

class BookBreadcrumbBuilder implements BreadcrumbBuilderInterface {
  ...
  public function build(RouteMatchInterface $route_match) {
    // Prepare array $links.
    ...
    // Wrap the array of link in a breadcrumb object.
    $breadcrumb = new Breadcrumb();
    $breadcrumb->setLinks($links);
    // Set metadata for caching.
    $breadcrumb->addCacheContexts(['route.book_navigation']);
    // Return the breadcrumb object.
    return $breadcrumb;
  }
  ...
}

This change is valid for all implementations of BreadcrumbBuilderInterface, e.g. BookBreadcrumbBuilder, CommentBreadcrumbBuilder, BreadcrumbManager and many others.

hook_system_breadcrumb_alter()

Before

The first argument of this hook is an array of breadcrumbs.

function hook_system_breadcrumb_alter(array &$breadcrumb, \Drupal\Core\Routing\RouteMatchInterface $route_match, array $context)

After

The first argument of this hook is instance of Breadcrumb.

function hook_system_breadcrumb_alter(\Drupal\Core\Breadcrumb\Breadcrumb &$breadcrumb, \Drupal\Core\Routing\RouteMatchInterface $route_match, array $context)

This change is valid for all implemenations of hook_system_breadcrumb_alter(). The only implementation in Drupal core is currently menu_ui_system_breadcrumb_alter().