Key Takeaways

• Plugin derivatives in Drupal 8 allow for the dynamic declaration of multiple instances of the same plugin, transforming user-configured functionality into plugins.
• Deriver classes are used to provide a list of plugin definitions that are based on the initial plugin but have slightly different configuration or definition data.
• The DerivativeDiscoveryDecorator in the plugin manager is used to retrieve derivatives, looking for a deriver class on each plugin and asking it for the list.
• While plugin derivatives are a powerful tool, they can be complex to set up and manage, especially for developers new to Drupal or unfamiliar with its plugin system. Careful management and testing are required as changes to the base plugin can impact all its derivatives.

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 DrupalCoreBlockAnnotationBlock 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

/**
 * @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;
  }
}

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

What are Drupal 8 Plugin Derivatives and why are they important?

Drupal 8 Plugin Derivatives are a powerful feature of Drupal 8 that allow developers to dynamically generate multiple instances of a single plugin. This is particularly useful when you have a large number of similar tasks to perform, but each task requires slightly different configuration. By using plugin derivatives, you can create a single base plugin and then generate as many variations of that plugin as you need, each with its own unique configuration. This can greatly simplify your code and make your Drupal 8 site more efficient and easier to manage.

How do I create a Drupal 8 Plugin Derivative?

Creating a Drupal 8 Plugin Derivative involves several steps. First, you need to create a base plugin that defines the basic functionality that all derivatives will share. Next, you need to create a plugin derivative class that extends the base plugin and implements the DerivativeInterface. This class is responsible for generating the individual derivatives. Finally, you need to register your plugin derivative with Drupal’s plugin manager so that it can be discovered and used.

Can I use Drupal 8 Plugin Derivatives with custom modules?

Yes, Drupal 8 Plugin Derivatives can be used with custom modules. In fact, they are particularly useful in this context, as they allow you to create a single base module and then generate multiple variations of that module, each with its own unique configuration. This can greatly simplify the development process and make your custom modules more efficient and easier to manage.

What are some common use cases for Drupal 8 Plugin Derivatives?

Drupal 8 Plugin Derivatives are incredibly versatile and can be used in a wide range of scenarios. Some common use cases include creating multiple instances of a block plugin, each with a different configuration; generating multiple menu links from a single base plugin; and creating multiple variations of a custom module, each tailored to a specific task or requirement.

How do I manage and maintain Drupal 8 Plugin Derivatives?

Managing and maintaining Drupal 8 Plugin Derivatives involves keeping track of the base plugin and all its derivatives, ensuring that they are all up-to-date and functioning correctly. This can be done through Drupal’s plugin manager, which provides a centralized interface for managing all your plugins. Additionally, it’s important to regularly review and update your plugin derivatives to ensure they continue to meet your needs and the needs of your site’s users.

Are there any limitations or challenges with using Drupal 8 Plugin Derivatives?

While Drupal 8 Plugin Derivatives are a powerful tool, they do come with some challenges. One of the main challenges is that they can be complex to set up and manage, particularly for developers who are new to Drupal or not familiar with its plugin system. Additionally, because each derivative is a variation of a single base plugin, changes to the base plugin can potentially impact all its derivatives, so careful management and testing are required.

Can I use Drupal 8 Plugin Derivatives with third-party plugins?

Yes, Drupal 8 Plugin Derivatives can be used with third-party plugins. However, it’s important to note that not all third-party plugins are designed to support derivatives, so you may need to do some additional work to make them compatible. Always check the documentation for the specific plugin you’re using to see if it supports derivatives and how to implement them.

How do Drupal 8 Plugin Derivatives improve site performance?

Drupal 8 Plugin Derivatives can improve site performance by reducing the amount of code that needs to be executed for each task. By creating a single base plugin and then generating multiple derivatives, you can avoid having to write and execute separate code for each task. This can result in a significant performance boost, particularly for sites with a large number of similar tasks.

How do I debug issues with Drupal 8 Plugin Derivatives?

Debugging issues with Drupal 8 Plugin Derivatives can be challenging due to their dynamic nature. However, Drupal provides several tools and techniques to help with this. One of the most useful is the Devel module, which provides a range of debugging and development tools. Additionally, Drupal’s error logging and reporting features can provide valuable information about any issues that arise.

Where can I find more resources on using Drupal 8 Plugin Derivatives effectively?

There are many resources available online for learning more about Drupal 8 Plugin Derivatives. The official Drupal documentation is a great place to start, as it provides comprehensive information on all aspects of Drupal development, including plugin derivatives. Additionally, there are many tutorials, blog posts, and forum discussions available that cover this topic in depth.

The above is the detailed content of Tutorial on Using Drupal 8 Plugin Derivatives Effectively. For more information, please follow other related articles on the PHP Chinese website!