Change record status: 
Project: 
Introduced in branch: 
8.3.x
Introduced in version: 
8.3.0
Description: 

None of the following changes affect existing plugin types.

When the Plugin System was first added to core, all plugin types used an array to contain their definition. Over time new plugin types were added that use an object-based definition instead.

In order to standardize this approach, several interfaces have been added.

All plugin definitions must be either an array or an implementation of \Drupal\Component\Plugin\Definition\PluginDefinitionInterface.
This provides 4 methods: id(), getProvider(), getClass() and setClass().

Core examples of classes using this interface are \Drupal\Core\Entity\EntityType and \Drupal\Core\Layout\LayoutDefinition.
For ease of use there is also a base class \Drupal\Component\Plugin\Definition\PluginDefinition.

Array-based plugin definitions use derivatives by providing a 'deriver' key with the value of a class implementing \Drupal\Component\Plugin\Derivative\DeriverInterface.
Object-based plugin definitions can implement \Drupal\Component\Plugin\Definition\DerivablePluginDefinitionInterface, and calling code will use the getDeriver() method.

Most plugin types implement \Drupal\Component\Plugin\DependentPluginInterface, which allows the plugin instance to define any dependencies. If the plugin definition also needs to define dependencies (usually in conjunction with derivatives), it may implement \Drupal\Core\Plugin\Definition\DependentPluginDefinitionInterface. This is analogous to an array-based definition using a 'config_dependencies' key. See \Drupal\Core\Config\Entity\ConfigDependencyManager for more information on dependencies.

Finally, it can be common for plugin types to allow multiple means of discovery. For example, both annotated classes and YAML-based definitions. Because the annotation process allows complex manipulation, it can be useful to ensure that other non-annotated definitions are processed the same way. Using \Drupal\Component\Annotation\Plugin\Discovery\AnnotationBridgeDecorator in your plugin manager ensures that all array-based definitions are run through the annotation process.
For example, from LayoutPluginManager:

  protected function getDiscovery() {
    if (!$this->discovery) {
      $discovery = new AnnotatedClassDiscovery('Plugin/Layout', $this->namespaces, '\Drupal\Core\Layout\Annotation\Layout', $this->additionalAnnotationNamespaces);
      $discovery = new YamlDiscoveryDecorator($discovery, 'layouts', $this->moduleHandler->getModuleDirectories() + $this->themeHandler->getThemeDirectories());
      $discovery = new AnnotationBridgeDecorator($discovery, '\Drupal\Core\Layout\Annotation\Layout');
      $discovery = new DerivativeDiscoveryDecorator($discovery);
      $this->discovery = $discovery;
    }
    return $this->discovery;
  }
Impacts: 
Module developers
Updates Done (doc team, etc.)
Online documentation: 
Not done
Theming guide: 
Not done
Module developer documentation: 
Not done
Examples project: 
Not done
Coder Review: 
Not done
Coder Upgrade: 
Not done
Other: 
Other updates done