DefaultPluginManager.php 11.1 KB
Newer Older
1 2 3 4
<?php

namespace Drupal\Core\Plugin;

5
use Drupal\Component\Assertion\Inspector;
6
use Drupal\Component\Plugin\Definition\PluginDefinitionInterface;
7
use Drupal\Component\Plugin\Discovery\CachedDiscoveryInterface;
8
use Drupal\Core\Cache\CacheableDependencyInterface;
9 10
use Drupal\Core\Cache\CacheBackendInterface;
use Drupal\Core\Cache\UseCacheBackendTrait;
11
use Drupal\Component\Plugin\Discovery\DiscoveryCachedTrait;
12
use Drupal\Core\Plugin\Discovery\ContainerDerivativeDiscoveryDecorator;
13 14 15
use Drupal\Component\Plugin\PluginManagerBase;
use Drupal\Component\Plugin\PluginManagerInterface;
use Drupal\Component\Utility\NestedArray;
16
use Drupal\Core\Cache\Cache;
17 18 19 20 21 22
use Drupal\Core\Extension\ModuleHandlerInterface;
use Drupal\Core\Plugin\Discovery\AnnotatedClassDiscovery;
use Drupal\Core\Plugin\Factory\ContainerFactory;

/**
 * Base class for plugin managers.
23 24
 *
 * @ingroup plugin_api
25
 */
26
class DefaultPluginManager extends PluginManagerBase implements PluginManagerInterface, CachedDiscoveryInterface, CacheableDependencyInterface {
27

28
  use DiscoveryCachedTrait;
29
  use UseCacheBackendTrait;
30 31

  /**
32
   * The cache key.
33 34 35 36 37
   *
   * @var string
   */
  protected $cacheKey;

38 39 40 41 42
  /**
   * An array of cache tags to use for the cached definitions.
   *
   * @var array
   */
43
  protected $cacheTags = [];
44

45 46 47 48 49 50 51 52
  /**
   * Name of the alter hook if one should be invoked.
   *
   * @var string
   */
  protected $alterHook;

  /**
53 54
   * The subdirectory within a namespace to look for plugins, or FALSE if the
   * plugins are in the top level of the namespace.
55
   *
56
   * @var string|bool
57 58 59 60 61 62 63 64 65 66
   */
  protected $subdir;

  /**
   * The module handler to invoke the alter hook.
   *
   * @var \Drupal\Core\Extension\ModuleHandlerInterface
   */
  protected $moduleHandler;

67 68 69 70 71 72 73
  /**
   * A set of defaults to be referenced by $this->processDefinition() if
   * additional processing of plugins is necessary or helpful for development
   * purposes.
   *
   * @var array
   */
74
  protected $defaults = [];
75

76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97
  /**
   * The name of the annotation that contains the plugin definition.
   *
   * @var string
   */
  protected $pluginDefinitionAnnotationName;

  /**
   * The interface each plugin should implement.
   *
   * @var string|null
   */
  protected $pluginInterface;

  /**
   * An object that implements \Traversable which contains the root paths
   * keyed by the corresponding namespace to look for plugin implementations.
   *
   * @var \Traversable
   */
  protected $namespaces;

98 99 100 101 102 103 104 105
  /**
   * Additional namespaces the annotation discovery mechanism should scan for
   * annotation definitions.
   *
   * @var string[]
   */
  protected $additionalAnnotationNamespaces = [];

106 107 108
  /**
   * Creates the discovery object.
   *
109 110
   * @param string|bool $subdir
   *   The plugin's subdirectory, for example Plugin/views/filter.
111 112
   * @param \Traversable $namespaces
   *   An object that implements \Traversable which contains the root paths
113
   *   keyed by the corresponding namespace to look for plugin implementations.
114 115
   * @param \Drupal\Core\Extension\ModuleHandlerInterface $module_handler
   *   The module handler.
116 117
   * @param string|null $plugin_interface
   *   (optional) The interface each plugin should implement.
118 119 120
   * @param string $plugin_definition_annotation_name
   *   (optional) The name of the annotation that contains the plugin definition.
   *   Defaults to 'Drupal\Component\Annotation\Plugin'.
121 122
   * @param string[] $additional_annotation_namespaces
   *   (optional) Additional namespaces to scan for annotation definitions.
123
   */
124
  public function __construct($subdir, \Traversable $namespaces, ModuleHandlerInterface $module_handler, $plugin_interface = NULL, $plugin_definition_annotation_name = 'Drupal\Component\Annotation\Plugin', array $additional_annotation_namespaces = []) {
125
    $this->subdir = $subdir;
126 127 128
    $this->namespaces = $namespaces;
    $this->pluginDefinitionAnnotationName = $plugin_definition_annotation_name;
    $this->pluginInterface = $plugin_interface;
129
    $this->moduleHandler = $module_handler;
130
    $this->additionalAnnotationNamespaces = $additional_annotation_namespaces;
131 132 133 134 135
  }

  /**
   * Initialize the cache backend.
   *
136
   * Plugin definitions are cached using the provided cache backend.
137 138 139
   *
   * @param \Drupal\Core\Cache\CacheBackendInterface $cache_backend
   *   Cache backend instance to use.
140
   * @param string $cache_key
141
   *   Cache key prefix to use.
142
   * @param array $cache_tags
143 144 145 146 147 148 149
   *   (optional) When providing a list of cache tags, the cached plugin
   *   definitions are tagged with the provided cache tags. These cache tags can
   *   then be used to clear the corresponding cached plugin definitions. Note
   *   that this should be used with care! For clearing all cached plugin
   *   definitions of a plugin manager, call that plugin manager's
   *   clearCachedDefinitions() method. Only use cache tags when cached plugin
   *   definitions should be cleared along with other, related cache entries.
150
   */
151
  public function setCacheBackend(CacheBackendInterface $cache_backend, $cache_key, array $cache_tags = []) {
152
    assert(Inspector::assertAllStrings($cache_tags), 'Cache Tags must be strings.');
153
    $this->cacheBackend = $cache_backend;
154
    $this->cacheKey = $cache_key;
155
    $this->cacheTags = $cache_tags;
156 157 158
  }

  /**
159
   * Sets the alter hook name.
160 161
   *
   * @param string $alter_hook
162 163
   *   Name of the alter hook; for example, to invoke
   *   hook_mymodule_data_alter() pass in "mymodule_data".
164
   */
165
  protected function alterInfo($alter_hook) {
166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185
    $this->alterHook = $alter_hook;
  }

  /**
   * {@inheritdoc}
   */
  public function getDefinitions() {
    $definitions = $this->getCachedDefinitions();
    if (!isset($definitions)) {
      $definitions = $this->findDefinitions();
      $this->setCachedDefinitions($definitions);
    }
    return $definitions;
  }

  /**
   * {@inheritdoc}
   */
  public function clearCachedDefinitions() {
    if ($this->cacheBackend) {
186 187
      if ($this->cacheTags) {
        // Use the cache tags to clear the cache.
188
        Cache::invalidateTags($this->cacheTags);
189
      }
190 191 192
      else {
        $this->cacheBackend->delete($this->cacheKey);
      }
193 194 195 196 197 198 199
    }
    $this->definitions = NULL;
  }

  /**
   * Returns the cached plugin definitions of the decorated discovery class.
   *
200
   * @return array|null
201 202 203 204 205 206
   *   On success this will return an array of plugin definitions. On failure
   *   this should return NULL, indicating to other methods that this has not
   *   yet been defined. Success with no values should return as an empty array
   *   and would actually be returned by the getDefinitions() method.
   */
  protected function getCachedDefinitions() {
207
    if (!isset($this->definitions) && $cache = $this->cacheGet($this->cacheKey)) {
208 209 210 211 212 213 214 215 216 217 218 219
      $this->definitions = $cache->data;
    }
    return $this->definitions;
  }

  /**
   * Sets a cache of plugin definitions for the decorated discovery class.
   *
   * @param array $definitions
   *   List of definitions to store in cache.
   */
  protected function setCachedDefinitions($definitions) {
220
    $this->cacheSet($this->cacheKey, $definitions, Cache::PERMANENT, $this->cacheTags);
221 222 223
    $this->definitions = $definitions;
  }

224 225 226 227 228 229 230 231 232 233
  /**
   * {@inheritdoc}
   */
  public function useCaches($use_caches = FALSE) {
    $this->useCaches = $use_caches;
    if (!$use_caches) {
      $this->definitions = NULL;
    }
  }

234 235 236 237 238 239 240 241
  /**
   * Performs extra processing on plugin definitions.
   *
   * By default we add defaults for the type to the definition. If a type has
   * additional processing logic they can do that by replacing or extending the
   * method.
   */
  public function processDefinition(&$definition, $plugin_id) {
242 243 244
    // Only array-based definitions can have defaults merged in.
    if (is_array($definition) && !empty($this->defaults) && is_array($this->defaults)) {
      $definition = NestedArray::mergeDeep($this->defaults, $definition);
245 246
    }

247 248 249 250 251 252
    // Keep class definitions standard with no leading slash.
    if ($definition instanceof PluginDefinitionInterface) {
      $definition->setClass(ltrim($definition->getClass(), '\\'));
    }
    elseif (is_array($definition) && isset($definition['class'])) {
      $definition['class'] = ltrim($definition['class'], '\\');
253 254 255
    }
  }

256 257 258 259 260
  /**
   * {@inheritdoc}
   */
  protected function getDiscovery() {
    if (!$this->discovery) {
261
      $discovery = new AnnotatedClassDiscovery($this->subdir, $this->namespaces, $this->pluginDefinitionAnnotationName, $this->additionalAnnotationNamespaces);
262 263 264 265 266 267 268 269 270 271 272 273 274 275 276
      $this->discovery = new ContainerDerivativeDiscoveryDecorator($discovery);
    }
    return $this->discovery;
  }

  /**
   * {@inheritdoc}
   */
  protected function getFactory() {
    if (!$this->factory) {
      $this->factory = new ContainerFactory($this, $this->pluginInterface);
    }
    return $this->factory;
  }

277 278 279 280 281 282 283
  /**
   * Finds plugin definitions.
   *
   * @return array
   *   List of definitions to store in cache.
   */
  protected function findDefinitions() {
284
    $definitions = $this->getDiscovery()->getDefinitions();
285 286 287
    foreach ($definitions as $plugin_id => &$definition) {
      $this->processDefinition($definition, $plugin_id);
    }
288
    $this->alterDefinitions($definitions);
289 290 291
    // If this plugin was provided by a module that does not exist, remove the
    // plugin definition.
    foreach ($definitions as $plugin_id => $plugin_definition) {
292
      $provider = $this->extractProviderFromDefinition($plugin_definition);
293
      if ($provider && !in_array($provider, ['core', 'component']) && !$this->providerExists($provider)) {
294 295 296
        unset($definitions[$plugin_id]);
      }
    }
297 298 299
    return $definitions;
  }

300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324
  /**
   * Extracts the provider from a plugin definition.
   *
   * @param mixed $plugin_definition
   *   The plugin definition. Usually either an array or an instance of
   *   \Drupal\Component\Plugin\Definition\PluginDefinitionInterface
   *
   * @return string|null
   *   The provider string, if it exists. NULL otherwise.
   */
  protected function extractProviderFromDefinition($plugin_definition) {
    if ($plugin_definition instanceof PluginDefinitionInterface) {
      return $plugin_definition->getProvider();
    }

    // Attempt to convert the plugin definition to an array.
    if (is_object($plugin_definition)) {
      $plugin_definition = (array) $plugin_definition;
    }

    if (isset($plugin_definition['provider'])) {
      return $plugin_definition['provider'];
    }
  }

325 326 327 328
  /**
   * Invokes the hook to alter the definitions if the alter hook is set.
   *
   * @param $definitions
329
   *   The discovered plugin definitions.
330 331 332 333 334 335 336
   */
  protected function alterDefinitions(&$definitions) {
    if ($this->alterHook) {
      $this->moduleHandler->alter($this->alterHook, $definitions);
    }
  }

337 338 339
  /**
   * Determines if the provider of a definition exists.
   *
340
   * @return bool
341 342 343 344 345 346
   *   TRUE if provider exists, FALSE otherwise.
   */
  protected function providerExists($provider) {
    return $this->moduleHandler->moduleExists($provider);
  }

347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364
  /**
   * {@inheritdoc}
   */
  public function getCacheContexts() {
    return [];
  }

  /**
   * {@inheritdoc}
   */
  public function getCacheTags() {
    return $this->cacheTags;
  }

  /**
   * {@inheritdoc}
   */
  public function getCacheMaxAge() {
365
    return Cache::PERMANENT;
366 367
  }

368
}