Using the Plugin API
The basic idea of plugins is to allow a particular module or subsystem of Drupal to provide functionality in an extensible, object-oriented way. The controlling module or subsystem defines the basic framework (interface) for the functionality, and other modules can create plugins (implementing the interface) with particular behaviors. The controlling module instantiates existing plugins as needed, and calls methods to invoke their functionality. Examples of functionality in Drupal Core that use plugins include: the block system (block types are plugins), the entity/field system (entity types, field types, field formatters, and field widgets are plugins), the image manipulation system (image effects and image toolkits are plugins), and the search system (search page types are plugins).
Plugins are grouped into plugin types, each generally defined by an interface. Each plugin type is managed by a plugin manager service, which uses a plugin discovery method to discover provided plugins of that type and instantiate them using a plugin factory.
Some plugin types make use of the following concepts or components:
There are several things a module developer may need to do with plugins:
See https://www.drupal.org/developing/api/8/plugins for more detailed documentation on the plugin system. There are also topics for a few of the many existing types of plugins:
To define a new plugin type:
Plugin discovery is the process your plugin manager uses to discover the individual plugins of your type that have been defined by your module and other modules. Plugin discovery methods are classes that implement \Drupal\Component\Plugin\Discovery\DiscoveryInterface. Most plugin types use one of the following discovery mechanisms:
It is also possible to define your own custom discovery mechanism or mix methods together. And there are many more details, such as annotation decorators, that apply to some of the discovery methods. See https://www.drupal.org/developing/api/8/plugins for more details.
The remainder of this documentation will assume Annotation-based discovery, since this is the most common method.
To define an annotation-based plugin manager:
plugin.manager.mymodule: class: Drupal\mymodule\MyPluginManager parent: default_plugin_manager
Some configurable plugin types allow administrators to create zero or more instances of each plugin, each with its own configuration. For example, a single block plugin can be configured several times, to display in different regions of a theme, with different visibility settings, a different title, or other plugin-specific settings. To make this possible, a plugin type can make use of what's known as a plugin collection.
A plugin collection is a class that extends \Drupal\Component\Plugin\LazyPluginCollection or one of its subclasses; there are several examples in Drupal Core. If your plugin type uses a plugin collection, it will usually also have a configuration entity, and the entity class should implement \Drupal\Core\Entity\EntityWithPluginCollectionInterface. Again, there are several examples in Drupal Core; see also the Configuration API topic for more information about configuration entities.
Assuming the plugin type uses annotation-based discovery, in order to create a plugin of an existing type, you will be creating a class. This class must:
Often, the easiest way to make sure this happens is to find an existing example of a working plugin class of the desired type, and copy it into your module as a starting point.
You can also create a plugin derivative, which allows your plugin class to present itself to the user interface as multiple plugins. To do this, in addition to the plugin class, you'll need to create a separate plugin derivative class implementing \Drupal\Component\Plugin\Derivative\DerivativeInterface. The classes \Drupal\system\Plugin\Block\SystemMenuBlock (plugin class) and \Drupal\system\Plugin\Derivative\SystemMenuBlock (derivative class) are a good example to look at.
Here are the steps to follow to perform a task that involves plugins:
Name | Location | Description |
---|---|---|
Condition | core/lib/Drupal/Core/Condition/Annotation/Condition.php | Defines a condition plugin annotation object. |
ConditionManager | core/lib/Drupal/Core/Condition/ConditionManager.php | A plugin manager for condition plugins. |
ConditionPluginBase | core/lib/Drupal/Core/Condition/ConditionPluginBase.php | Provides a basis for fulfilling contexts for condition plugins. |
DefaultPluginManager | core/lib/Drupal/Core/Plugin/DefaultPluginManager.php | Base class for plugin managers. |
LazyPluginCollection | core/lib/Drupal/Component/Plugin/LazyPluginCollection.php | Defines an object which stores multiple plugin instances to lazy load them. |
Plugin | core/lib/Drupal/Component/Annotation/Plugin.php | Defines a Plugin annotation object. |
PluginBase | core/lib/Drupal/Core/Plugin/PluginBase.php | Base class for plugins supporting metadata inspection and translation. |
Name | Location | Description |
---|---|---|
ConditionInterface | core/lib/Drupal/Core/Condition/ConditionInterface.php | An interface for condition plugins. |
ConfigurablePluginInterface | core/lib/Drupal/Component/Plugin/ConfigurablePluginInterface.php | Provides an interface for a configurable plugin. |
ContextAwarePluginInterface | core/lib/Drupal/Core/Plugin/ContextAwarePluginInterface.php | An override of ContextAwarePluginInterface for documentation purposes. |
ContextAwarePluginInterface | core/lib/Drupal/Component/Plugin/ContextAwarePluginInterface.php | Interface for defining context aware plugins. |
DependentPluginInterface | core/lib/Drupal/Component/Plugin/DependentPluginInterface.php | Provides an interface for a plugin that has dependencies. |
DeriverInterface | core/lib/Drupal/Component/Plugin/Derivative/DeriverInterface.php | Provides additional plugin definitions based on an existing definition. |
DiscoveryInterface | core/lib/Drupal/Component/Plugin/Discovery/DiscoveryInterface.php | An interface defining the minimum requirements of building a plugin discovery component. |
EntityWithPluginCollectionInterface | core/lib/Drupal/Core/Entity/EntityWithPluginCollectionInterface.php | Provides an interface for an object using a plugin collection. |
ExecutableInterface | core/lib/Drupal/Core/Executable/ExecutableInterface.php | An interface for executable plugins. |
ObjectWithPluginCollectionInterface | core/lib/Drupal/Core/Plugin/ObjectWithPluginCollectionInterface.php | Provides an interface for an object using a plugin collection. |
PluginFormInterface | core/lib/Drupal/Core/Plugin/PluginFormInterface.php | Provides an interface for an embeddable plugin form. |
PluginInspectionInterface | core/lib/Drupal/Component/Plugin/PluginInspectionInterface.php | Plugin interface for providing some metadata inspection. |
PluginManagerInterface | core/lib/Drupal/Component/Plugin/PluginManagerInterface.php | Interface implemented by plugin managers. |
© 2001–2016 by the original authors
Licensed under the GNU General Public License, version 2 and later.
Drupal is a registered trademark of Dries Buytaert.
https://api.drupal.org/api/drupal/core!core.api.php/group/plugin_api/8.1.x