Picture a power strip with six identical sockets. The strip doesn't know or care what you plug into each one — a lamp, a phone charger, a fan — as long as the plug fits the socket's shape. Drupal's plugin system is that power strip, generalized into a full architecture: a fixed "socket" (an interface and some conventions) that any number of independent, swappable "appliances" (plugin implementations) can fit into, discovered automatically without anyone maintaining a master list by hand.
What you'll learn in this lesson
- The core problem plugins solve, and why hooks alone don't solve it
- The three pieces every plugin type needs: a manager, a discovery mechanism, and a common interface
- How annotation-based discovery lets Drupal find plugins without a registration step
- Where you've probably already used plugins without realizing it
The problem: swappable behavior, discovered automatically
Say you want site builders to choose from a growing list of interchangeable things — block types, field formatters, image effects, migration sources. Each option needs the same basic shape (a way to be identified, labeled, and instantiated) but completely different internal behavior. You could write one giant switch statement, but every module that wanted to add a new option would have to edit that switch — impossible for options that ship in separate, unrelated modules. Drupal's plugin system exists specifically to let independent modules contribute new implementations of a shared concept without ever touching each other's code.
The three pieces of a plugin type
Every plugin type in Drupal core — and every custom one you build — is made of the same three pieces:
- An interface — the contract every implementation must fulfill (e.g. every Block plugin must be able to
build()its render array). - A plugin manager — a service, usually extending
\Drupal\Core\Plugin\DefaultPluginManager, responsible for finding, caching, and instantiating implementations. - A discovery mechanism — most commonly annotation-based: the manager scans a specific subdirectory (like
src/Plugin/Block) across every enabled module, looking for classes carrying a matching annotation.
Here's a real plugin manager constructor, from the Examples module's own plugin_type_example (a deliberately simple, from-scratch plugin type built around "sandwiches"):
class SandwichPluginManager extends DefaultPluginManager {
public function __construct(\Traversable $namespaces, CacheBackendInterface $cache_backend, ModuleHandlerInterface $module_handler) {
// Tells the manager to look for Sandwich plugins in the
// 'src/Plugin/Sandwich' subdirectory of any enabled module.
$subdir = 'Plugin/Sandwich';
// The interface every sandwich plugin must implement.
$plugin_interface = SandwichInterface::class;
// The annotation class that documents a sandwich plugin's metadata.
$plugin_definition_annotation_name = Sandwich::class;
parent::__construct($subdir, $namespaces, $module_handler, $plugin_interface, $plugin_definition_annotation_name);
$this->alterInfo('sandwich_info');
$this->setCacheBackend($cache_backend, 'sandwich_info', ['sandwich_info']);
}
}Notice what this constructor does not do: it never lists individual sandwiches. It just tells Drupal where to look (Plugin/Sandwich) and what shape to expect (SandwichInterface, annotated with @Sandwich(...)). Any module — including one that doesn't exist yet — can drop a class into that subdirectory and it's discovered automatically the next time the plugin cache is rebuilt.
Why this beats a hook for this problem
Hooks are great for "let every interested module react to or alter one specific thing." Plugins solve a different problem: "let any number of modules each contribute one complete, self-contained, interchangeable implementation of a concept," where each implementation typically needs its own class, its own state, and sometimes its own configuration form. Trying to force that shape into a hook would mean one giant function with a branch per implementation — exactly the maintenance problem plugins were designed to avoid.
Quick check: if a contributed module wants to add a brand-new block type to your site, does it need permission from — or even awareness of — any other module that also defines blocks? (No. Because discovery is annotation-based and automatic, any module can add a new Block plugin independently. Neither module needs to know the other exists.)
Key takeaways
- A plugin type is built from three pieces: an interface (the contract), a manager (finds and instantiates), and a discovery mechanism (usually annotations).
- Plugins solve "many interchangeable implementations of one concept," which is a different problem from what hooks solve ("many reactions to one event").
- Discovery is automatic — a plugin manager never maintains a hand-written list of implementations; it scans a known subdirectory across all enabled modules instead.
- Blocks, field types, field widgets, field formatters, image effects, and migrate plugins are all built on this exact same underlying architecture.
Coming up next
Understanding the pieces is one thing — building your own plugin type from scratch is another. In the next lesson you'll define a brand-new plugin type, writing the manager, interface, and annotation class that make a plugin type exist at all, before any implementations are written against it.