www.aleph1.co.uk Git - yaffs-website/blob - web/core/lib/Drupal/Core/Plugin/Context/ContextProviderInterface.php

   1 <?php
   2
   3 namespace Drupal\Core\Plugin\Context;
   4
   5 /**
   6  * Defines an interface for providing plugin contexts.
   7  *
   8  * Implementations only need to deal with unqualified context IDs so they only
   9  * need to be unique in the context of a given service provider.
  10  *
  11  * The fully qualified context ID then includes the service ID:
  12  * @{service_id}:{unqualified_context_id}.
  13  *
  14  * @see \Drupal\Core\Plugin\Context\ContextRepositoryInterface
  15  */
  16 interface ContextProviderInterface {
  17
  18   /**
  19    * Gets runtime context values for the given context IDs.
  20    *
  21    * For context-aware plugins to function correctly, all of the contexts that
  22    * they require must be populated with values. So this method should set a
  23    * value for each context that it adds. For example:
  24    *
  25    * @code
  26    *   // Determine a specific node to pass as context to a block.
  27    *   $node = ...
  28    *
  29    *   // Set that specific node as the value of the 'node' context.
  30    *   $context = new Context(new ContextDefinition('entity:node'), $node);
  31    *   return ['node' => $context];
  32    * @endcode
  33    *
  34    * On the other hand, there are cases, on which providers no longer are
  35    * possible to provide context objects, even without the value, so the caller
  36    * should not expect it.
  37    *
  38    * @param string[] $unqualified_context_ids
  39    *   The requested context IDs. The context provider must only return contexts
  40    *   for those IDs.
  41    *
  42    * @return \Drupal\Core\Plugin\Context\ContextInterface[]
  43    *   The determined available contexts, keyed by the unqualified context_id.
  44    *
  45    * @see \Drupal\Core\Plugin\Context\ContextProviderInterface:getAvailableContexts()
  46    */
  47   public function getRuntimeContexts(array $unqualified_context_ids);
  48
  49   /**
  50    * Gets all available contexts for the purposes of configuration.
  51    *
  52    * When a context aware plugin is being configured, the configuration UI must
  53    * know which named contexts are potentially available, but does not care
  54    * about the value, since the value can be different for each request, and
  55    * might not be available at all during the configuration UI's request.
  56    *
  57    * For example:
  58    * @code
  59    *   // During configuration, there is no specific node to pass as context.
  60    *   // However, inform the system that a context named 'node' is
  61    *   // available, and provide its definition, so that context aware plugins
  62    *   // can be configured to use it. When the plugin, for example a block,
  63    *   // needs to evaluate the context, the value of this context will be
  64    *   // supplied by getRuntimeContexts().
  65    *   $context = new Context(new ContextDefinition('entity:node'));
  66    *   return ['node' => $context];
  67    * @endcode
  68    *
  69    * @return \Drupal\Core\Plugin\Context\ContextInterface[]
  70    *   All available contexts keyed by the unqualified context ID.
  71    *
  72    * @see \Drupal\Core\Plugin\Context\ContextProviderInterface::getRuntimeContext()
  73    */
  74   public function getAvailableContexts();
  75
  76 }