Plugin API in Drupal

The Drupal plugin system allows a particular module or subsystem to provide functionality in an extensible, object-oriented way. The controlling module defines the basic framework (interface) for the functionality, and other modules can create plugins (implementing the interface) with particular behaviors. Plugins are grouped into plugin types. 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.

The system aims to make it easy for developers to allow for management of these components via the user interface, giving more flexibility and control to site administrators.

In this tutorial we'll take a high-level look at the problem the Plugin API is solving and provide a starting point for diving deeper into the various components that make up the Plugin API.

The term plugin type is used as a way to provide a generic name for all plugins managed by the same plugin manager. Example plugin types include block, field widget, and image effect. A plugin type doesn't consist of any code that provides specific functionality. Instead, it provides a way to refer to the system and it describes the central purpose of all plugins of that type.

In this tutorial, we'll cover what the term plugin type means and how it is used when talking about Drupal's plugin system. By the end of this tutorial, you'll understand what a plugin type is and be ready to learn how to define a plugin type in a module.

Knowing how to define a new plugin type will allow you to write modules that are more extensible, and more configurable. In doing so you'll learn more about best practices in decoupling code within your module, and get an in-depth look at how the plugin system works. Even if you're not defining a new plugin type in your own module, understanding how the system works will give you more insight into how many parts of Drupal work. This is essential knowledge for anyone developing modules for Drupal.

By the end of this tutorial you should be able to determine if defining a new plugin type is the right solution to your problem, and then understand the steps involved in doing so.

Knowing which plugin types exist and the use case for each is important when it comes to writing modules that extend Drupal's existing functionality. If you want to add additional functionality, you need to first know which plugin type provides that functionality.

In this tutorial, we'll list some of the more commonly-used plugin types and their use case, show where you can find a more complete list of plugin types provided by core, and provide several methods for discovering existing plugins in your Drupal codebase.

Before you can create a new plugin of any type you'll need to figure out where the plugin implementation and its metadata should live in the code base so that the plugin manager can find plugins and examine what functionality instances of the plugin type are expected to provide.

This tutorial contains 2 parts:

• A recipe and example of how to implement a plugin if you already know the plugin type.
• How to figure out a specific plugin type's implementation details.

In this tutorial we'll:

• Provide a recipe for implementing plugins of any type.
• Demonstrate how to figure out where the code and metadata should live for PHP-based plugins.
• Explain how to figure out where YAML plugin definitions should go, and what they should contain.

By the end of this tutorial you should have a recipe for getting started with implementing annotation-based plugins, and YAML-based plugins, and a better understanding of how to figure out the details required to implement any given plugin type.

A plugin manager is responsible for both the definition of a new plugin type, and for listing and instantiating instances of plugins of the defined type.

In this tutorial we'll:

• Define what a plugin manager is
• Create a list of all plugins of a specific type
• Load and instantiate specific plugin instances so we can use them in our code

In order for a plugin manager to locate instances of individual plugins within the Drupal code base it needs to know where to look, and how to interpret the data that it finds. This process is called plugin discovery and can be accomplished in a few different ways.

In this tutorial we'll look at what plugin discovery is doing at a high level, and then talk about the various plugin discovery methods you can choose from when defining a new plugin type.

Learn how the Plugin API takes a given plugin ID and uses it to instantiate and return a fully configured plugin object. In this tutorial we'll look at:

• What factories are, and the role they serve in the Plugin API
• The factories available in core
• Using mappers to dynamically load a plugin when you don't know the ID of the specific plugin you need.

Plugin derivatives allow a single plugin to dynamically generate multiple plugin instances based on configuration or other data. This is useful for situations where user-entered data, or other dynamic configuration, might have an impact on available plugins. Or, put another way, any time you need to be able to dynamically generate plugin definitions.

In this tutorial we'll:

• Define what plugin derivatives are
• Understand the use case for derivatives
• Examine how core uses derivatives in order to demonstrate how you could write your own plugin deriver class