Chris@0: <?php
Chris@0: 
Chris@0: namespace Drupal\Component\Plugin;
Chris@0: 
Chris@0: use Drupal\Component\Plugin\Context\ContextInterface;
Chris@0: 
Chris@0: /**
Chris@0:  * Interface for defining context aware plugins.
Chris@0:  *
Chris@0:  * Context aware plugins can specify an array of context definitions keyed by
Chris@0:  * context name at the plugin definition under the "context" key.
Chris@0:  *
Chris@0:  * @ingroup plugin_api
Chris@0:  */
Chris@0: interface ContextAwarePluginInterface extends PluginInspectionInterface {
Chris@0: 
Chris@0:   /**
Chris@0:    * Gets the context definitions of the plugin.
Chris@0:    *
Chris@0:    * @return \Drupal\Component\Plugin\Context\ContextDefinitionInterface[]
Chris@0:    *   The array of context definitions, keyed by context name.
Chris@0:    */
Chris@0:   public function getContextDefinitions();
Chris@0: 
Chris@0:   /**
Chris@0:    * Gets a specific context definition of the plugin.
Chris@0:    *
Chris@0:    * @param string $name
Chris@0:    *   The name of the context in the plugin definition.
Chris@0:    *
Chris@0:    * @return \Drupal\Component\Plugin\Context\ContextDefinitionInterface
Chris@0:    *   The definition against which the context value must validate.
Chris@0:    *
Chris@0:    * @throws \Drupal\Component\Plugin\Exception\PluginException
Chris@0:    *   If the requested context is not defined.
Chris@0:    */
Chris@0:   public function getContextDefinition($name);
Chris@0: 
Chris@0:   /**
Chris@0:    * Gets the defined contexts.
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   The set context objects.
Chris@0:    *
Chris@0:    * @throws \Drupal\Component\Plugin\Exception\PluginException
Chris@0:    *   If contexts are defined but not set.
Chris@0:    */
Chris@0:   public function getContexts();
Chris@0: 
Chris@0:   /**
Chris@0:    * Gets a defined context.
Chris@0:    *
Chris@0:    * @param string $name
Chris@0:    *   The name of the context in the plugin definition.
Chris@0:    *
Chris@0:    * @return \Drupal\Component\Plugin\Context\ContextInterface
Chris@0:    *   The context object.
Chris@0:    *
Chris@0:    * @throws \Drupal\Component\Plugin\Exception\PluginException
Chris@0:    *   If the requested context is not set.
Chris@0:    */
Chris@0:   public function getContext($name);
Chris@0: 
Chris@0:   /**
Chris@0:    * Gets the values for all defined contexts.
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   An array of set context values, keyed by context name. If a context is
Chris@0:    *   unset its value is returned as NULL.
Chris@0:    */
Chris@0:   public function getContextValues();
Chris@0: 
Chris@0:   /**
Chris@0:    * Gets the value for a defined context.
Chris@0:    *
Chris@0:    * @param string $name
Chris@0:    *   The name of the context in the plugin configuration.
Chris@0:    *
Chris@0:    * @return mixed
Chris@0:    *   The currently set context value.
Chris@0:    *
Chris@0:    * @throws \Drupal\Component\Plugin\Exception\PluginException
Chris@0:    *   If the requested context is not set.
Chris@0:    */
Chris@0:   public function getContextValue($name);
Chris@0: 
Chris@0:   /**
Chris@0:    * Set a context on this plugin.
Chris@0:    *
Chris@0:    * @param string $name
Chris@0:    *   The name of the context in the plugin configuration.
Chris@0:    * @param \Drupal\Component\Plugin\Context\ContextInterface $context
Chris@0:    *   The context object to set.
Chris@0:    */
Chris@0:   public function setContext($name, ContextInterface $context);
Chris@0: 
Chris@0:   /**
Chris@0:    * Sets the value for a defined context.
Chris@0:    *
Chris@0:    * @param string $name
Chris@0:    *   The name of the context in the plugin definition.
Chris@0:    * @param mixed $value
Chris@0:    *   The value to set the context to. The value has to validate against the
Chris@0:    *   provided context definition.
Chris@0:    *
Chris@0:    * @return \Drupal\Component\Plugin\ContextAwarePluginInterface
Chris@0:    *   A context aware plugin object for chaining.
Chris@0:    *
Chris@0:    * @throws \Drupal\Component\Plugin\Exception\PluginException
Chris@0:    *   If the value does not pass validation.
Chris@0:    */
Chris@0:   public function setContextValue($name, $value);
Chris@0: 
Chris@0:   /**
Chris@0:    * Validates the set values for the defined contexts.
Chris@0:    *
Chris@0:    * @return \Symfony\Component\Validator\ConstraintViolationListInterface
Chris@0:    *   A list of constraint violations. If the list is empty, validation
Chris@0:    *   succeeded.
Chris@0:    */
Chris@0:   public function validateContexts();
Chris@0: 
Chris@0:   /**
Chris@0:    * Gets a mapping of the expected assignment names to their context names.
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   A mapping of the expected assignment names to their context names. For
Chris@0:    *   example, if one of the $contexts is named 'user.current_user', but the
Chris@0:    *   plugin expects a context named 'user', then this map would contain
Chris@0:    *   'user' => 'user.current_user'.
Chris@0:    */
Chris@0:   public function getContextMapping();
Chris@0: 
Chris@0:   /**
Chris@0:    * Sets a mapping of the expected assignment names to their context names.
Chris@0:    *
Chris@0:    * @param array $context_mapping
Chris@0:    *   A mapping of the expected assignment names to their context names. For
Chris@0:    *   example, if one of the $contexts is named 'user.current_user', but the
Chris@0:    *   plugin expects a context named 'user', then this map would contain
Chris@0:    *   'user' => 'user.current_user'.
Chris@0:    *
Chris@0:    * @return $this
Chris@0:    */
Chris@0:   public function setContextMapping(array $context_mapping);
Chris@0: 
Chris@0: }