Chris@0: <?php
Chris@0: 
Chris@0: namespace Drupal\Core\Annotation;
Chris@0: 
Chris@0: use Drupal\Component\Annotation\Plugin;
Chris@0: use Drupal\Core\StringTranslation\TranslatableMarkup;
Chris@0: 
Chris@0: /**
Chris@0:  * @defgroup plugin_context Annotation for context definition
Chris@0:  * @{
Chris@0:  * Describes how to use ContextDefinition annotation.
Chris@0:  *
Chris@0:  * When providing plugin annotations, contexts can be defined to support UI
Chris@0:  * interactions through providing limits, and mapping contexts to appropriate
Chris@0:  * plugins. Context definitions can be provided as such:
Chris@0:  * @code
Chris@0:  *   context = {
Chris@0:  *     "node" = @ContextDefinition("entity:node")
Chris@0:  *   }
Chris@0:  * @endcode
Chris@0:  *
Chris@0:  * To add a label to a context definition use the "label" key:
Chris@0:  * @code
Chris@0:  *   context = {
Chris@0:  *     "node" = @ContextDefinition("entity:node", label = @Translation("Node"))
Chris@0:  *   }
Chris@0:  * @endcode
Chris@0:  *
Chris@0:  * Contexts are required unless otherwise specified. To make an optional
Chris@0:  * context use the "required" key:
Chris@0:  * @code
Chris@0:  *   context = {
Chris@0:  *     "node" = @ContextDefinition("entity:node", required = FALSE, label = @Translation("Node"))
Chris@0:  *   }
Chris@0:  * @endcode
Chris@0:  *
Chris@0:  * To define multiple contexts, simply provide different key names in the
Chris@0:  * context array:
Chris@0:  * @code
Chris@0:  *   context = {
Chris@0:  *     "artist" = @ContextDefinition("entity:node", label = @Translation("Artist")),
Chris@0:  *     "album" = @ContextDefinition("entity:node", label = @Translation("Album"))
Chris@0:  *   }
Chris@0:  * @endcode
Chris@0:  *
Chris@0:  * Specifying a default value for the context definition:
Chris@0:  * @code
Chris@0:  *   context = {
Chris@0:  *     "message" = @ContextDefinition("string",
Chris@0:  *       label = @Translation("Message"),
Chris@0:  *       default_value = @Translation("Checkout complete! Thank you for your purchase.")
Chris@0:  *     )
Chris@0:  *   }
Chris@0:  * @endcode
Chris@0:  *
Chris@0:  * @see annotation
Chris@0:  *
Chris@0:  * @}
Chris@0:  */
Chris@0: 
Chris@0: /**
Chris@0:  * Defines a context definition annotation object.
Chris@0:  *
Chris@0:  * Some plugins require various data contexts in order to function. This class
Chris@0:  * supports that need by allowing the contexts to be easily defined within an
Chris@0:  * annotation and return a ContextDefinitionInterface implementing class.
Chris@0:  *
Chris@0:  * @Annotation
Chris@0:  *
Chris@0:  * @ingroup plugin_context
Chris@0:  */
Chris@0: class ContextDefinition extends Plugin {
Chris@0: 
Chris@0:   /**
Chris@0:    * The ContextDefinitionInterface object.
Chris@0:    *
Chris@0:    * @var \Drupal\Core\Plugin\Context\ContextDefinitionInterface
Chris@0:    */
Chris@0:   protected $definition;
Chris@0: 
Chris@0:   /**
Chris@0:    * Constructs a new context definition object.
Chris@0:    *
Chris@0:    * @param array $values
Chris@0:    *   An associative array with the following keys:
Chris@0:    *   - value: The required data type.
Chris@0:    *   - label: (optional) The UI label of this context definition.
Chris@0:    *   - required: (optional) Whether the context definition is required.
Chris@0:    *   - multiple: (optional) Whether the context definition is multivalue.
Chris@0:    *   - description: (optional) The UI description of this context definition.
Chris@0:    *   - default_value: (optional) The default value in case the underlying
Chris@0:    *     value is not set.
Chris@0:    *   - class: (optional) A custom ContextDefinitionInterface class.
Chris@0:    *
Chris@0:    * @throws \Exception
Chris@0:    *   Thrown when the class key is specified with a non
Chris@0:    *   ContextDefinitionInterface implementing class.
Chris@0:    */
Chris@0:   public function __construct(array $values) {
Chris@0:     $values += [
Chris@0:       'required' => TRUE,
Chris@0:       'multiple' => FALSE,
Chris@0:       'default_value' => NULL,
Chris@0:     ];
Chris@0:     // Annotation classes extract data from passed annotation classes directly
Chris@0:     // used in the classes they pass to.
Chris@0:     foreach (['label', 'description'] as $key) {
Chris@0:       // @todo Remove this workaround in https://www.drupal.org/node/2362727.
Chris@0:       if (isset($values[$key]) && $values[$key] instanceof TranslatableMarkup) {
Chris@0:         $values[$key] = (string) $values[$key]->get();
Chris@0:       }
Chris@0:       else {
Chris@0:         $values[$key] = NULL;
Chris@0:       }
Chris@0:     }
Chris@0:     if (isset($values['class']) && !in_array('Drupal\Core\Plugin\Context\ContextDefinitionInterface', class_implements($values['class']))) {
Chris@0:       throw new \Exception('ContextDefinition class must implement \Drupal\Core\Plugin\Context\ContextDefinitionInterface.');
Chris@0:     }
Chris@0:     $class = isset($values['class']) ? $values['class'] : 'Drupal\Core\Plugin\Context\ContextDefinition';
Chris@0:     $this->definition = new $class($values['value'], $values['label'], $values['required'], $values['multiple'], $values['description'], $values['default_value']);
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Returns the value of an annotation.
Chris@0:    *
Chris@0:    * @return \Drupal\Core\Plugin\Context\ContextDefinitionInterface
Chris@0:    */
Chris@0:   public function get() {
Chris@0:     return $this->definition;
Chris@0:   }
Chris@0: 
Chris@0: }