Drupal 8  8.0.2
Plugin API

Data Structures

class  Plugin
 
interface  ConfigurablePluginInterface
 
interface  ContextAwarePluginInterface
 
interface  DependentPluginInterface
 
interface  DeriverInterface
 
interface  DiscoveryInterface
 
class  LazyPluginCollection
 
interface  PluginInspectionInterface
 
interface  PluginManagerInterface
 
class  Condition
 
interface  ConditionInterface
 
class  ConditionManager
 
class  ConditionPluginBase
 
interface  EntityWithPluginCollectionInterface
 
interface  ExecutableInterface
 
class  DefaultPluginManager
 
class  PluginBase
 
interface  PluginFormInterface
 

Detailed Description

Using the Plugin API

Overview and terminology

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:

Defining a new plugin type

To define a new plugin type:

Plugin discovery

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

Defining a plugin manager class and service

To define an annotation-based plugin manager:

Defining a plugin collection

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 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 . Again, there are several examples in Drupal Core; see also the Configuration API topic for more information about configuration entities.

Creating a plugin of an existing type

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:

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 . The classes (plugin class) and (derivative class) are a good example to look at.

Performing tasks involving plugins

Here are the steps to follow to perform a task that involves plugins:

See Also
Annotations