Issue #1875996 by Xano, tim.plunkett, neclimdul, Rajendar Reddy, Jalandhar:...

Issue #1875996 by Xano, tim.plunkett, neclimdul, Rajendar Reddy, Jalandhar: Reconsider naming conventions for derivative classes.

core/lib/Drupal/Component/Plugin/Derivative/DerivativeBase.php → core/lib/Drupal/Component/Plugin/Derivative/DeriverBase.php

@@ -2,20 +2,15 @@
 
 /**
  * @file
- * Contains Drupal\Component\Plugin\Derivative\DerivativeBase.
+ * Contains \Drupal\Component\Plugin\Derivative\DeriverBase.
  */
 
 namespace Drupal\Component\Plugin\Derivative;
 
-use Drupal\Component\Plugin\Derivative\DerivativeInterface;
-
 /**
- * Default version of getDerivativeDefinition() common to most concrete
- * implementations of DerivativeInterface.
- *
- * See the Aggregator and Mock block derivers for different implementations.
+ * Provides a basic deriver.
  */
-abstract class DerivativeBase implements DerivativeInterface {
+abstract class DeriverBase implements DeriverInterface {
 
   /**
    * List of derivative definitions.

core/lib/Drupal/Component/Plugin/Derivative/DerivativeInterface.php → core/lib/Drupal/Component/Plugin/Derivative/DeriverInterface.php

@@ -2,17 +2,17 @@
 
 /**
  * @file
- * Definition of Drupal\Component\Plugin\Derivative\DerivativeInterface.
+ * Contains \Drupal\Component\Plugin\Derivative\DeriverInterface.
  */
 
 namespace Drupal\Component\Plugin\Derivative;
 
 /**
- * Plugin interface for derivative plugin handling.
+ * Provides additional plugin definitions based on an existing definition.
  *
  * @ingroup plugin_api
  */
-interface DerivativeInterface {
+interface DeriverInterface {
 
   /**
    * Returns the definition of a derivative plugin.

core/lib/Drupal/Component/Plugin/DerivativeInspectionInterface.php

@@ -18,7 +18,7 @@ interface DerivativeInspectionInterface {
    * @return string
    *   The base_plugin_id of the plugin instance.
    */
-  public function getBasePluginId();
+  public function getBaseId();
 
   /**
    * Returns the derivative_id of the plugin instance.

core/lib/Drupal/Component/Plugin/Discovery/DerivativeDiscoveryDecorator.php

@@ -7,7 +7,7 @@
 
 namespace Drupal\Component\Plugin\Discovery;
 
-use Drupal\Component\Plugin\Exception\InvalidDerivativeClassException;
+use Drupal\Component\Plugin\Exception\InvalidDeriverException;
 
 /**
  * Base class providing the tools for a plugin discovery to be derivative aware.
@@ -19,14 +19,25 @@ class DerivativeDiscoveryDecorator implements DiscoveryInterface {
 
   use DiscoveryTrait;
 
-  protected $derivativeFetchers = array();
+  /**
+   * Plugin derivers.
+   *
+   * @var \Drupal\Component\Plugin\Derivative\DeriverInterface[]
+   *   Keys are base plugin IDs.
+   */
+  protected $derivers = array();
+
+  /**
+   * The decorated plugin discovery.
+   *
+   * @var \Drupal\Component\Plugin\Discovery\DiscoveryInterface
+   */
   protected $decorated;
 
   /**
-   * Creates a Drupal\Component\Plugin\Discovery\DerivativeDiscoveryDecorator
-   * object.
+   * Creates a new instance.
    *
-   * @param DiscoveryInterface $discovery
+   * @param \Drupal\Component\Plugin\Discovery\DiscoveryInterface $decorated
    *   The parent object implementing DiscoveryInterface that is being
    *   decorated.
    */
@@ -37,9 +48,9 @@ public function __construct(DiscoveryInterface $decorated) {
   /**
    * {@inheritdoc}
    *
-   * @throws \Drupal\Component\Plugin\Exception\InvalidDerivativeClassException
-   *   Thrown if the 'derivative' class specified in the plugin definition does
-   *   not implement \Drupal\Component\Plugin\Derivative\DerivativeInterface.
+   * @throws \Drupal\Component\Plugin\Exception\InvalidDeriverException
+   *   Thrown if the 'deriver' class specified in the plugin definition
+   *   does not implement \Drupal\Component\Plugin\Derivative\DeriverInterface.
    */
   public function getDefinition($plugin_id, $exception_on_invalid = TRUE) {
     // This check is only for derivative plugins that have explicitly provided
@@ -51,9 +62,9 @@ public function getDefinition($plugin_id, $exception_on_invalid = TRUE) {
     list($base_plugin_id, $derivative_id) = $this->decodePluginId($plugin_id);
     $base_plugin_definition = $this->decorated->getDefinition($base_plugin_id, $exception_on_invalid);
     if ($base_plugin_definition) {
-      $derivative_fetcher = $this->getDerivativeFetcher($base_plugin_id, $base_plugin_definition);
-      if ($derivative_fetcher) {
-        $derivative_plugin_definition = $derivative_fetcher->getDerivativeDefinition($derivative_id, $base_plugin_definition);
+      $deriver = $this->getDeriver($base_plugin_id, $base_plugin_definition);
+      if ($deriver) {
+        $derivative_plugin_definition = $deriver->getDerivativeDefinition($derivative_id, $base_plugin_definition);
         // If a plugin defined itself as a derivative, merge in possible
         // defaults from the derivative.
         if ($derivative_id && isset($plugin_definition)) {
@@ -71,9 +82,9 @@ public function getDefinition($plugin_id, $exception_on_invalid = TRUE) {
   /**
    * {@inheritdoc}
    *
-   * @throws \Drupal\Component\Plugin\Exception\InvalidDerivativeClassException
-   *   Thrown if the 'derivative' class specified in the plugin definition does
-   *   not implement \Drupal\Component\Plugin\Derivative\DerivativeInterface.
+   * @throws \Drupal\Component\Plugin\Exception\InvalidDeriverException
+   *   Thrown if the 'deriver' class specified in the plugin definition
+   *   does not implement \Drupal\Component\Plugin\Derivative\DeriverInterface.
    */
   public function getDefinitions() {
     $plugin_definitions = $this->decorated->getDefinitions();
@@ -89,9 +100,9 @@ public function getDefinitions() {
   protected function getDerivatives(array $base_plugin_definitions) {
     $plugin_definitions = array();
     foreach ($base_plugin_definitions as $base_plugin_id => $plugin_definition) {
-      $derivative_fetcher = $this->getDerivativeFetcher($base_plugin_id, $plugin_definition);
-      if ($derivative_fetcher) {
-        $derivative_definitions = $derivative_fetcher->getDerivativeDefinitions($plugin_definition);
+      $deriver = $this->getDeriver($base_plugin_id, $plugin_definition);
+      if ($deriver) {
+        $derivative_definitions = $deriver->getDerivativeDefinitions($plugin_definition);
         foreach ($derivative_definitions as $derivative_id => $derivative_definition) {
           $plugin_id = $this->encodePluginId($base_plugin_id, $derivative_id);
           // Use this definition as defaults if a plugin already defined
@@ -155,52 +166,51 @@ protected function encodePluginId($base_plugin_id, $derivative_id) {
   }
 
   /**
-   * Finds a Drupal\Component\Plugin\Discovery\DerivativeInterface.
-   *
-   * This Drupal\Component\Plugin\Discovery\DerivativeInterface can fetch
-   * derivatives for the plugin.
+   * Gets a deriver for a base plugin.
    *
    * @param string $base_plugin_id
    *   The base plugin id of the plugin.
    * @param mixed $base_definition
    *   The base plugin definition to build derivatives.
    *
-   * @return \Drupal\Component\Plugin\Derivative\DerivativeInterface|null
+   * @return \Drupal\Component\Plugin\Derivative\DeriverInterface|null
    *   A DerivativeInterface or NULL if none exists for the plugin.
    *
-   * @throws \Drupal\Component\Plugin\Exception\InvalidDerivativeClassException
-   *   Thrown if the 'derivative' class specified in the plugin definition does
-   *   not implement \Drupal\Component\Plugin\Derivative\DerivativeInterface.
+   * @throws \Drupal\Component\Plugin\Exception\InvalidDeriverException
+   *   Thrown if the 'deriver' class specified in the plugin definition
+   *   does not implement \Drupal\Component\Plugin\Derivative\DeriverInterface.
    */
-  protected function getDerivativeFetcher($base_plugin_id, $base_definition) {
-    if (!isset($this->derivativeFetchers[$base_plugin_id])) {
-      $this->derivativeFetchers[$base_plugin_id] = FALSE;
-      $class = $this->getDerivativeClass($base_definition);
+  protected function getDeriver($base_plugin_id, $base_definition) {
+    if (!isset($this->derivers[$base_plugin_id])) {
+      $this->derivers[$base_plugin_id] = FALSE;
+      $class = $this->getDeriverClass($base_definition);
       if ($class) {
-        $this->derivativeFetchers[$base_plugin_id] = new $class($base_plugin_id);
+        $this->derivers[$base_plugin_id] = new $class($base_plugin_id);
       }
     }
-    return $this->derivativeFetchers[$base_plugin_id] ?: NULL;
+    return $this->derivers[$base_plugin_id] ?: NULL;
   }
 
   /**
-   * Get the derivative class name from the base plugin definition.
+   * Get the deriver class name from the base plugin definition.
    *
    * @param array $base_definition
    *   The base plugin definition to build derivatives.
    *
-   * @return string|NULL
-   *   The name of a class implementing \Drupal\Component\Plugin\Derivative\DerivativeInterface.
+   * @return string|null
+   *   The name of a class implementing
+   *   \Drupal\Component\Plugin\Derivative\DeriverInterface.
    *
-   * @throws \Drupal\Component\Plugin\Exception\InvalidDerivativeClassException
-   *   Thrown if the 'derivative' class specified in the plugin definition does
-   *   not implement \Drupal\Component\Plugin\Derivative\DerivativeInterface.
+   * @throws \Drupal\Component\Plugin\Exception\InvalidDeriverException
+   *   Thrown if the 'deriver' class specified in the plugin definition
+   *   does not implement
+   *   \Drupal\Component\Plugin\Derivative\DerivativeInterface.
    */
-  protected function getDerivativeClass($base_definition) {
+  protected function getDeriverClass($base_definition) {
     $class = NULL;
-    if ((is_array($base_definition) || ($base_definition = (array) $base_definition)) && (isset($base_definition['derivative']) && $class = $base_definition['derivative'])) {
-      if (!is_subclass_of($class, '\Drupal\Component\Plugin\Derivative\DerivativeInterface')) {
-        throw new InvalidDerivativeClassException(sprintf('Plugin (%s) derivative class "%s" has to implement interface \Drupal\Component\Plugin\Derivative\DerivativeInterface', $base_definition['id'], $class));
+    if ((is_array($base_definition) || ($base_definition = (array) $base_definition)) && (isset($base_definition['deriver']) && $class = $base_definition['deriver'])) {
+      if (!is_subclass_of($class, '\Drupal\Component\Plugin\Derivative\DeriverInterface')) {
+        throw new InvalidDeriverException(sprintf('Plugin (%s) deriver "%s" must implement \Drupal\Component\Plugin\Derivative\DeriverInterface', $base_definition['id'], $class));
       }
     }
     return $class;

core/lib/Drupal/Component/Plugin/Exception/InvalidDerivativeClassException.php → core/lib/Drupal/Component/Plugin/Exception/InvalidDeriverException.php

 <?php
 /**
  * @file
- * Definition of \Drupal\Component\Plugin\Exception\InvalidDerivativeClassException.
+ * Definition of \Drupal\Component\Plugin\Exception\InvalidDeriverClassException.
  */
 
 namespace Drupal\Component\Plugin\Exception;
 
 /**
- * Exception to be thrown if a plugin tries to use an invalid derivative class.
+ * Exception to be thrown if a plugin tries to use an invalid deriver.
  */
-class InvalidDerivativeClassException extends PluginException { }
+class InvalidDeriverException extends PluginException { }

core/lib/Drupal/Component/Plugin/Factory/DefaultFactory.php

@@ -8,7 +8,7 @@
 
 use Drupal\Component\Plugin\Discovery\DiscoveryInterface;
 use Drupal\Component\Plugin\Exception\PluginException;
-use Drupal\Component\Plugin\Derivative\DerivativeInterface;
+use Drupal\Component\Plugin\Derivative\DeriverInterface;
 
 /**
  * Default plugin factory.

core/lib/Drupal/Component/Plugin/PluginBase.php

@@ -70,7 +70,7 @@ public function getPluginId() {
   /**
    * {@inheritdoc}
    */
-  public function getBasePluginId() {
+  public function getBaseId() {
     $plugin_id = $this->getPluginId();
     if (strpos($plugin_id, static::DERIVATIVE_SEPARATOR)) {
       list($plugin_id) = explode(static::DERIVATIVE_SEPARATOR, $plugin_id, 2);

core/lib/Drupal/Core/Entity/Plugin/DataType/Deriver/EntityDeriver.php

@@ -8,13 +8,13 @@
 namespace Drupal\Core\Entity\Plugin\DataType\Deriver;
 
 use Drupal\Core\Entity\EntityManagerInterface;
-use Drupal\Core\Plugin\Discovery\ContainerDerivativeInterface;
+use Drupal\Core\Plugin\Discovery\ContainerDeriverInterface;
 use Symfony\Component\DependencyInjection\ContainerInterface;
 
 /**
  * Provides data type plugins for each existing entity type and bundle.
  */
-class EntityDeriver implements ContainerDerivativeInterface {
+class EntityDeriver implements ContainerDeriverInterface {
 
   /**
    * List of derivative definitions.

core/lib/Drupal/Core/Entity/Plugin/DataType/Entity.php

@@ -17,7 +17,7 @@
  *   id = "entity",
  *   label = @Translation("Entity"),
  *   description = @Translation("All kind of entities, e.g. nodes, comments or users."),
- *   derivative = "\Drupal\Core\Entity\Plugin\DataType\Deriver\EntityDeriver",
+ *   deriver = "\Drupal\Core\Entity\Plugin\DataType\Deriver\EntityDeriver",
  *   definition_class = "\Drupal\Core\Entity\TypedData\EntityDataDefinition"
  * )
  */

core/lib/Drupal/Core/Field/Plugin/DataType/Deriver/FieldItemDeriver.php

@@ -8,13 +8,13 @@
 namespace Drupal\Core\Field\Plugin\DataType\Deriver;
 
 use Drupal\Core\Field\FieldTypePluginManagerInterface;
-use Drupal\Core\Plugin\Discovery\ContainerDerivativeInterface;
+use Drupal\Core\Plugin\Discovery\ContainerDeriverInterface;
 use Symfony\Component\DependencyInjection\ContainerInterface;
 
 /**
  * Provides data type plugins for each existing field type plugin.
  */
-class FieldItemDeriver implements ContainerDerivativeInterface {
+class FieldItemDeriver implements ContainerDeriverInterface {
 
   /**
    * List of derivative definitions.

core/lib/Drupal/Core/Field/Plugin/DataType/FieldItem.php

@@ -18,7 +18,7 @@
  *   id = "field_item",
  *   label = @Translation("Field item"),
  *   list_class = "\Drupal\Core\Field\FieldItemList",
- *   derivative = "Drupal\Core\Field\Plugin\DataType\Deriver\FieldItemDeriver"
+ *   deriver = "Drupal\Core\Field\Plugin\DataType\Deriver\FieldItemDeriver"
  * )
  */
 abstract class FieldItem {

core/lib/Drupal/Core/Plugin/Discovery/ContainerDerivativeDiscoveryDecorator.php

@@ -14,22 +14,22 @@ class ContainerDerivativeDiscoveryDecorator extends DerivativeDiscoveryDecorator
   /**
    * {@inheritdoc}
    */
-  protected function getDerivativeFetcher($base_plugin_id, $base_definition) {
-    if (!isset($this->derivativeFetchers[$base_plugin_id])) {
-      $this->derivativeFetchers[$base_plugin_id] = FALSE;
-      $class = $this->getDerivativeClass($base_definition);
+  protected function getDeriver($base_plugin_id, $base_definition) {
+    if (!isset($this->derivers[$base_plugin_id])) {
+      $this->derivers[$base_plugin_id] = FALSE;
+      $class = $this->getDeriverClass($base_definition);
       if ($class) {
-        // If the derivative class provides a factory method, pass the container
-        // to it.
-        if (is_subclass_of($class, 'Drupal\Core\Plugin\Discovery\ContainerDerivativeInterface')) {
-          $this->derivativeFetchers[$base_plugin_id] = $class::create(\Drupal::getContainer(), $base_plugin_id);
+        // If the deriver provides a factory method, pass the container to it.
+        if (is_subclass_of($class, '\Drupal\Core\Plugin\Discovery\ContainerDeriverInterface')) {
+          /** @var \Drupal\Core\Plugin\Discovery\ContainerDeriverInterface $class */
+          $this->derivers[$base_plugin_id] = $class::create(\Drupal::getContainer(), $base_plugin_id);
         }
         else {
-          $this->derivativeFetchers[$base_plugin_id] = new $class($base_plugin_id);
+          $this->derivers[$base_plugin_id] = new $class($base_plugin_id);
         }
       }
     }
-    return $this->derivativeFetchers[$base_plugin_id] ?: NULL;
+    return $this->derivers[$base_plugin_id] ?: NULL;
   }
 
 }

core/lib/Drupal/Core/Plugin/Discovery/ContainerDerivativeInterface.php → core/lib/Drupal/Core/Plugin/Discovery/ContainerDeriverInterface.php

@@ -2,25 +2,26 @@
 
 /**
  * @file
- * Contains \Drupal\Core\Plugin\Discovery\ContainerDerivativeInterface.
+ * Contains \Drupal\Core\Plugin\Discovery\ContainerDeriverInterface.
  */
 
 namespace Drupal\Core\Plugin\Discovery;
 
-use Drupal\Component\Plugin\Derivative\DerivativeInterface;
+use Drupal\Component\Plugin\Derivative\DeriverInterface;
 use Symfony\Component\DependencyInjection\ContainerInterface;
 
 /**
- * Derivative fetcher interface to pass the container to static create method.
+ * Provides additional plugin definitions based on an existing definition using
+ * service injection.
  */
-interface ContainerDerivativeInterface extends DerivativeInterface {
+interface ContainerDeriverInterface extends DeriverInterface {
 
   /**
-   * Creates an instance of the derivative fetcher.
+   * Creates a new class instance.
    *
    * @param \Symfony\Component\DependencyInjection\ContainerInterface $container
    *   The container to pull out services used in the fetcher.
-   * @param string $plugin_id
+   * @param string $base_plugin_id
    *   The base plugin ID for the plugin ID.
    *
    * @return static

core/modules/block/block.local_tasks.yml

@@ -12,4 +12,4 @@ block.admin_display_theme:
   title: 'Block layout'
   route_name: block.admin_display_theme
   parent_id: block.admin_display
-  derivative: 'Drupal\block\Plugin\Derivative\ThemeLocalTask'
+  deriver: 'Drupal\block\Plugin\Derivative\ThemeLocalTask'

core/modules/block/custom_block/src/Plugin/Derivative/CustomBlock.php

+<?php
+
+/**
+ * @file
+ * Contains \Drupal\custom_block\Plugin\Derivative\CustomBlock.
+ */
+
+namespace Drupal\custom_block\Plugin\Derivative;
+
+use Drupal\Component\Plugin\Derivative\DeriverBase;
+use Drupal\Core\Plugin\Discovery\ContainerDeriverInterface;
+
+/**
+ * Retrieves block plugin definitions for all custom blocks.
+ */
+class CustomBlock extends DeriverBase {
+  /**
+   * {@inheritdoc}
+   */
+  public function getDerivativeDefinitions($base_plugin_definition) {
+    $custom_blocks = entity_load_multiple('custom_block');
+    foreach ($custom_blocks as $custom_block) {
+      $this->derivatives[$custom_block->uuid()] = $base_plugin_definition;
+      $this->derivatives[$custom_block->uuid()]['admin_label'] = $custom_block->label();
+    }
+    return parent::getDerivativeDefinitions($base_plugin_definition);
+  }
+}

core/modules/block/src/BlockPluginInterface.php

@@ -8,6 +8,7 @@
 namespace Drupal\block;
 
 use Drupal\Component\Plugin\Context\ContextInterface;
+use Drupal\Component\Plugin\DerivativeInspectionInterface;
 use Drupal\Core\Cache\CacheableInterface;
 use Drupal\Component\Plugin\PluginInspectionInterface;
 use Drupal\Component\Plugin\ConfigurablePluginInterface;
@@ -24,7 +25,7 @@
  *
  * @ingroup block_api
  */
-interface BlockPluginInterface extends ConfigurablePluginInterface, PluginFormInterface, PluginInspectionInterface, CacheableInterface {
+interface BlockPluginInterface extends ConfigurablePluginInterface, PluginFormInterface, PluginInspectionInterface, CacheableInterface, DerivativeInspectionInterface {
 
   /**
    * Returns the user-facing block label.

core/modules/block/src/BlockViewBuilder.php

@@ -37,12 +37,13 @@ public function view(EntityInterface $entity, $view_mode = 'full', $langcode = N
    * {@inheritdoc}
    */
   public function viewMultiple(array $entities = array(), $view_mode = 'full', $langcode = NULL) {
+    /** @var \Drupal\block\BlockInterface[] $entities */
     $build = array();
     foreach ($entities as  $entity) {
       $entity_id = $entity->id();
       $plugin = $entity->getPlugin();
       $plugin_id = $plugin->getPluginId();
-      $base_id = $plugin->getBasePluginId();
+      $base_id = $plugin->getBaseId();
       $derivative_id = $plugin->getDerivativeId();
       $configuration = $plugin->getConfiguration();
 

core/modules/block/src/Plugin/Derivative/ThemeLocalTask.php

@@ -7,16 +7,16 @@
 
 namespace Drupal\block\Plugin\Derivative;
 
-use Drupal\Component\Plugin\Derivative\DerivativeBase;
+use Drupal\Component\Plugin\Derivative\DeriverBase;
 use Drupal\Core\Config\ConfigFactoryInterface;
 use Drupal\Core\Extension\ThemeHandlerInterface;
-use Drupal\Core\Plugin\Discovery\ContainerDerivativeInterface;
+use Drupal\Core\Plugin\Discovery\ContainerDeriverInterface;
 use Symfony\Component\DependencyInjection\ContainerInterface;
 
 /**
  * Provides dynamic tabs based on active themes.
  */
-class ThemeLocalTask extends DerivativeBase implements ContainerDerivativeInterface {
+class ThemeLocalTask extends DeriverBase implements ContainerDeriverInterface {
 
   /**
    * Stores the theme settings config object.

core/modules/block/src/Tests/BlockPreprocessUnitTest.php

@@ -37,6 +37,7 @@ function testBlockClasses() {
     // an underscore (not transformed) and a hyphen (transformed to underscore),
     // and generates possibilities for each level of derivative.
     // @todo Clarify this comment.
+    /** @var \Drupal\block\BlockInterface $block */
     $block = entity_create('block', array(
       'plugin' => 'system_menu_block:admin',
       'region' => 'footer',
@@ -48,7 +49,7 @@ function testBlockClasses() {
     $plugin = $block->getPlugin();
     $variables['elements']['#configuration'] = $plugin->getConfiguration();
     $variables['elements']['#plugin_id'] = $plugin->getPluginId();
-    $variables['elements']['#base_plugin_id'] = $plugin->getBasePluginId();
+    $variables['elements']['#base_plugin_id'] = $plugin->getBaseId();
     $variables['elements']['#derivative_plugin_id'] = $plugin->getDerivativeId();
     $variables['elements']['content'] = array();
 

core/modules/block/src/Tests/BlockTemplateSuggestionsUnitTest.php

@@ -37,6 +37,7 @@ function testBlockThemeHookSuggestions() {
     // an underscore (not transformed) and a hyphen (transformed to underscore),
     // and generates possibilities for each level of derivative.
     // @todo Clarify this comment.
+    /** @var \Drupal\block\BlockInterface $block */
     $block = entity_create('block', array(
       'plugin' => 'system_menu_block:admin',
       'region' => 'footer',
@@ -48,7 +49,7 @@ function testBlockThemeHookSuggestions() {
     $variables['elements']['#configuration'] = $plugin->getConfiguration();
     $variables['elements']['#plugin_id'] = $plugin->getPluginId();
     $variables['elements']['#id'] = $block->id();
-    $variables['elements']['#base_plugin_id'] = $plugin->getBasePluginId();
+    $variables['elements']['#base_plugin_id'] = $plugin->getBaseId();
     $variables['elements']['#derivative_plugin_id'] = $plugin->getDerivativeId();
     $variables['elements']['content'] = array();
     $suggestions = block_theme_suggestions_block($variables);