Tutorial on Using Drupal 8 Plugin Derivatives Effectively

In an earlier tutorial, we looked at the Drupal 8 plugin system and how to create our very own custom plugin type. We’ve seen that much of the functionality declared via _info hooks in Drupal 7 has been replaced by these plugins. Our use case was very basic and it allowed each instance of such functionality to be declared manually via a new plugin class and associated form.

But what if we needed such instances declared dynamically depending on some factors external to our little subsystem? For example, when declaring _info hooks in Drupal 7, we can get a list of something, loop over it and declare a new item in the returned array for each individual something. The menu system does this in order to provide a new block for each menu that either comes with Drupal core or is later created through the UI.

So what about Drupal 8? We’ve seen that for each plugin of a certain type we need to declare a different PHP class. To create a new block, we need a new class. To create another block, we need another class. So where would that looping we see in Drupal 7 take place? The short answer to this is: within a plugin derivative.

In this article we will explore the long answer to that and learn what derivates are and how we can use them. For the latter, we will build an example inside the demo module that can be found in this git repository and which should hopefully help us better understand what’s going on. For a slightly more complex example, the Menu system is great as it provides an individual block for each of its menus (similar to Drupal 7 but using plugins).

What we are going to do is actually very simple. We are going to implement basic Node Block functionality by which for all the article nodes on our site we will have a block. Ridiculous? Sure. Should we be doing this for all the nodes on our site? Definitely not! But it’s a very basic implementation meant to keep things short and demonstrate the use of the plugin derivatives.

Plugin Derivatives

Plugin derivatives are the way through which a plugin of a certain type can be represented in the system as multiple instances of itself. In other words, a plugin can reference a deriver class which is responsible for providing a list of plugin definitions that are based on the initial plugin (start from the same base definition) but have slightly different configuration or definition data. The SystemMenuBlock we referred to above is a great example. It’s a single plugin which has as many derivatives as there are menus on the site.

To go a bit deeper, when a list of all the plugins of a certain type is requested, the plugin manager uses its discovery mechanism to load all the plugins of this type. If that mechanism is decorated with the DerivativeDiscoveryDecorator, the manager will be able to also retrieve derivatives. In order to do this, the derivative discovery looks for a deriver class on each plugin and, if it finds one, asks it for this list.

Plugin type managers that extend the DefaultPluginManager base class should normally have the derivative discovery mechanism decorating the default discovery (annotations). This is the most common pattern in the Drupal core plugin system: annotated discovery wrapped by derivatives.

The Derivative Class

Now that we know what the role of plugin derivatives is, let’s create our first deriver class that will be used by our block plugin (which we will create in a minute).

Inside src/Plugin/Derivative/NodeBlock.php of the demo module we have the following:

<?php

/**
 * @file
 * Contains \Drupal\demo\Plugin\Derivative\NodeBlock.
 */

namespace Drupal\demo\Plugin\Derivative;

use Drupal\Component\Plugin\Derivative\DeriverBase;
use Drupal\Core\Entity\EntityStorageInterface;
use Drupal\Core\Plugin\Discovery\ContainerDeriverInterface;
use Symfony\Component\DependencyInjection\ContainerInterface;

/**
 * Provides block plugin definitions for nodes.
 *
 * @see \Drupal\demo\Plugin\Block\NodeBlock
 */
class NodeBlock extends DeriverBase implements ContainerDeriverInterface {

  /**
   * The node storage.
   *
   * @var \Drupal\Core\Entity\EntityStorageInterface
   */
  protected $nodeStorage;

  /**
   * Constructs new NodeBlock.
   *
   * @param \Drupal\Core\Entity\EntityStorageInterface $node_storage
   *   The node storage.
   */
  public function __construct(EntityStorageInterface $node_storage) {
    $this->nodeStorage = $node_storage;
  }

  /**
   * {@inheritdoc}
   */
  public static function create(ContainerInterface $container, $base_plugin_id) {
    return new static(
      $container->get('entity.manager')->getStorage('node')
    );
  }

  /**
   * {@inheritdoc}
   */
  public function getDerivativeDefinitions($base_plugin_definition) {
    $nodes = $this->nodeStorage->loadByProperties(['type' => 'article']);
    foreach ($nodes as $node) {
      $this->derivatives[$node->id()] = $base_plugin_definition;
      $this->derivatives[$node->id()]['admin_label'] = t('Node block: ') . $node->label();
    }
    return $this->derivatives;
  }
}

All our class needs to implement is the DeriverInterface and implement its two methods. We use the ContainerDeriverInterface instead because we want to make our deriver container aware. Why? Because we use dependency injection to load Drupal’s entity manager so that we can access the Node storage (this is what the constructor and the create() method do). Additionally, our deriver class extends from the DeriverBase class because that already takes care of one of the required methods (getDerivativeDefinition()).

Finally, getDerivativeDefinitions() is the method responsible for providing an array of plugin definitions that derive from the plugin which uses this class. It receives the $base_plugin_definition as an argument (the definition of the actual plugin which uses this deriver) and we use that to build up our derivative definitions. In our case, we indiscriminately load all the Article nodes and, for each of them, create a separate definition which differs only by having a different admin_label (this is a property on the Drupal\Core\Block\Annotation\Block annotation class). The array of derivatives is keyed by the ID of the derivative (in our case the Node ID which we will use later).

A very important point we need to make here is that loading all the nodes and creating plugins out of them is never a good idea. What would be maybe interesting is to implement functionality by which individual nodes can be exposed as blocks via a checkbox or something like that.

The Block Plugin

Now that we have our deriver class, let’s create a simple block plugin that uses it to generate multiple instances of itself (one for each Article node).

Inside src/Plugin/Block/NodeBlock.php:

<?php

namespace Drupal\demo\Plugin\Block;

use Drupal\Core\Block\BlockBase;
use Drupal\Core\Entity\EntityManagerInterface;
use Drupal\Core\Entity\EntityViewBuilderInterface;
use Drupal\Core\Plugin\ContainerFactoryPluginInterface;
use Drupal\Core\Session\AccountInterface;
use Drupal\node\NodeInterface;
use Symfony\Component\DependencyInjection\ContainerInterface;

/**
 * Provides a 'NodeBlock' block plugin.
 *
 * @Block(
 *   id = "node_block",
 *   admin_label = @Translation("Node block"),
 *   deriver = "Drupal\demo\Plugin\Derivative\NodeBlock"
 * )
 */

class NodeBlock extends BlockBase implements ContainerFactoryPluginInterface {

  /**
   * @var EntityViewBuilderInterface.
   */
  private $viewBuilder;

  /**
   * @var NodeInterface.
   */
  private $node;

  /**
   * Creates a NodeBlock instance.
   *
   * @param array $configuration
   * @param string $plugin_id
   * @param array $plugin_definition
   * @param EntityManagerInterface $entity_manager
   */
  public function __construct(array $configuration, $plugin_id, $plugin_definition, EntityManagerInterface $entity_manager) {
    parent::__construct($configuration, $plugin_id, $plugin_definition);
    $this->viewBuilder = $entity_manager->getViewBuilder('node');
    $this->nodeStorage = $entity_manager->getStorage('node');
    $this->node = $entity_manager->getStorage('node')->load($this->getDerivativeId());
  }

  /**
   * {@inheritdoc}
   */
  public static function create(ContainerInterface $container, array $configuration, $plugin_id, $plugin_definition) {
    return new static(
      $configuration,
      $plugin_id,
      $plugin_definition,
      $container->get('entity.manager')
    );
  }
  
  /**
   * {@inheritdoc}
   */
  public function build() {
    if (!$this->node instanceof NodeInterface) {
      return;
    }
    $build = $this->viewBuilder->view($this->node, 'full');
    return $build;
  }
  
  /**
   * {@inheritdoc}
   */
  public function blockAccess(AccountInterface $account, $return_as_object = FALSE) {
    return $this->node->access('view', NULL, TRUE);
  }
}

The first thing we notice in this plugin’s annotation is the deriver key which points to the class we created before. And that is basically all we need to couple the two. The derivative discovery decorator handles the heavy lifting.

Much of the rest is basic block building we should be familiar with. What’s interesting is that we can use the getDerivativeId() method to retrieve the node ID we used also as the ID of the derivative being displayed and, using that, we load the node object and build the block as the actual node output. Lastly, inside the blockAccess() method we make sure that this block has the same access checks as the actual node itself. So if the current user doesn’t have access to view the current node, the block won’t even show up.

Now if we clear the caches and navigate to the Block Layout interface we should see some blocks called Node Block: [Node title]. You can place these where you want and they will render the relevant node.

Conclusion

In this article, we’ve looked at plugin derivatives and seen a simple example of how they work. The key take away on this topic is that plugin derivatives are the way we dynamically declare multiple instances of the same plugin. They usually help us transform user configured functionality (e.g. menus) into plugins (e.g. menu blocks).

To illustrate the use of derivatives, we’ve seen a very simple technique which allows us to render Article nodes as blocks. We should remember though not to try this out on a website with many Article nodes but rather implement additional functionality that limits the number of nodes that get exposed. You know, so we don’t crash our site.

Questions? Comments? Anything you’d like explained further? Let us know!

Frequently Asked Questions (FAQs) about Using Drupal 8 Plugin Derivatives Effectively