Defining a new plugin type with annotationsfor Drupal 8 , 9 , 10 , and 11

Building on our previous lesson about Drupal’s plugin architecture, it's time to dive into creating your own plugin type with annotations. This lesson will guide you through the process, helping you better understand the power of plugins in extending Drupal's functionality.

What Are Annotations?

Annotations in Drupal act as metadata to describe plugins. They define attributes directly in your PHP classes. This metadata is parsed and used by Drupal to understand how to handle your plugin. They follow the structure of PHPDoc comments and provide Drupal with information like IDs, labels, and classes needed to manage plugins effectively without additional configuration files.

Creating Your Plugin Type

To create a new plugin type, the process involves defining a Plugin Manager along with the associated interface and annotation definition. Here’s how you can get started:

Step 1: Create the Plugin Interface

The interface defines the methods that any plugin of this type must implement. Let’s create a simple calculator plugin type. Start by creating an interface named CalculatorInterface.php in the src/Plugin/Calculator directory.

namespace Drupal\your_module\Plugin\Calculator;

interface CalculatorInterface {
    /**
     * Perform a calculation.
     *
     * @return mixed
     *   The result of the calculation.
     */
    public function calculate();
}

Step 2: Define the Plugin Annotation

Create a new file named Calculator.php in the src/Annotation directory. This is where you'll define the annotation used to describe each plugin of this type.

namespace Drupal\your_module\Annotation;

use Drupal\Component\Annotation\Plugin;

/**
 * Defines a Calculator item annotation object.
 *
 * @Annotation
 */
class Calculator extends Plugin {
    /**
     * The plugin ID.
     *
     * @var string
     */
    public $id;
    
    /**
     * The human-readable name of the plugin type.
     *
     * @var \Drupal\Core\Annotation\Translation
     */
    public $label;
}

Step 3: Implement the Plugin Manager

Your plugin manager will handle the discovery and instantiation of plugins. Create a file named CalculatorManager.php in the src/Plugin/Calculator directory.

namespace Drupal\your_module\Plugin\Calculator;

use Drupal\Core\Plugin\DefaultPluginManager;

class CalculatorManager extends DefaultPluginManager {
    public function __construct(\Traversable $namespaces, \Drupal\Core\Cache\CacheBackendInterface $cache_backend, \Drupal\Core\Extension\ModuleHandlerInterface $module_handler) {
        parent::__construct('Plugin/Calculator', $namespaces, $module_handler, 'Drupal\your_module\Plugin\Calculator\CalculatorInterface', 'Drupal\your_module\Annotation\Calculator');
        $this->alterInfo('calculator_info');
        $this->setCacheBackend($cache_backend, 'calculator_plugins');
    }
}

Step 4: Create a Plugin Class

To create an actual plugin, you'll define a class that implements your interface and uses your annotation. Here's an example within the src/Plugin/Calculator/Addition.php file:

namespace Drupal\your_module\Plugin\Calculator;

use Drupal\your_module\Annotation\Calculator;

/**
 * Addition plugin implementation.
 *
 * @Calculator(
 *   id = "addition",
 *   label = @Translation("Addition")
 * )
 */
class Addition implements CalculatorInterface {
    public function calculate() {
        return array_sum(func_get_args());
    }
}

Integrating into Drupal

The last step is to register your service in the your_module.services.yml file to ensure Drupal knows about your custom plugin manager.

services:
  your_module.calculator_manager:
    class: Drupal\your_module\Plugin\Calculator\CalculatorManager
    arguments: ['@container.namespaces', '@cache.default', '@module_handler']

Conclusion

Congratulations! You've successfully defined a new plugin type using annotations in Drupal. This achievement not only helps you understand the anatomy of a plugin type but also improves your skills in creating modular and reusable components in Drupal.

In the next lesson, we will explore the intricacies of "Adding Annotation Metadata for Plugins," where we'll delve deeper into how the metadata enhances the functioning of plugins and what additional capabilities we can tag on to our custom plugin types. Stay curious and keep building!