annotate core/lib/Drupal/Component/Plugin/ContextAwarePluginInterface.php @ 19:fa3358dc1485 tip

Add ndrum files
author Chris Cannam
date Wed, 28 Aug 2019 13:14:47 +0100
parents 4c8ae668cc8c
children
rev   line source
Chris@0 1 <?php
Chris@0 2
Chris@0 3 namespace Drupal\Component\Plugin;
Chris@0 4
Chris@0 5 use Drupal\Component\Plugin\Context\ContextInterface;
Chris@0 6
Chris@0 7 /**
Chris@0 8 * Interface for defining context aware plugins.
Chris@0 9 *
Chris@0 10 * Context aware plugins can specify an array of context definitions keyed by
Chris@0 11 * context name at the plugin definition under the "context" key.
Chris@0 12 *
Chris@0 13 * @ingroup plugin_api
Chris@0 14 */
Chris@0 15 interface ContextAwarePluginInterface extends PluginInspectionInterface {
Chris@0 16
Chris@0 17 /**
Chris@0 18 * Gets the context definitions of the plugin.
Chris@0 19 *
Chris@0 20 * @return \Drupal\Component\Plugin\Context\ContextDefinitionInterface[]
Chris@0 21 * The array of context definitions, keyed by context name.
Chris@0 22 */
Chris@0 23 public function getContextDefinitions();
Chris@0 24
Chris@0 25 /**
Chris@0 26 * Gets a specific context definition of the plugin.
Chris@0 27 *
Chris@0 28 * @param string $name
Chris@0 29 * The name of the context in the plugin definition.
Chris@0 30 *
Chris@0 31 * @return \Drupal\Component\Plugin\Context\ContextDefinitionInterface
Chris@0 32 * The definition against which the context value must validate.
Chris@0 33 *
Chris@0 34 * @throws \Drupal\Component\Plugin\Exception\PluginException
Chris@0 35 * If the requested context is not defined.
Chris@0 36 */
Chris@0 37 public function getContextDefinition($name);
Chris@0 38
Chris@0 39 /**
Chris@0 40 * Gets the defined contexts.
Chris@0 41 *
Chris@0 42 * @return array
Chris@0 43 * The set context objects.
Chris@0 44 *
Chris@0 45 * @throws \Drupal\Component\Plugin\Exception\PluginException
Chris@0 46 * If contexts are defined but not set.
Chris@0 47 */
Chris@0 48 public function getContexts();
Chris@0 49
Chris@0 50 /**
Chris@0 51 * Gets a defined context.
Chris@0 52 *
Chris@0 53 * @param string $name
Chris@0 54 * The name of the context in the plugin definition.
Chris@0 55 *
Chris@0 56 * @return \Drupal\Component\Plugin\Context\ContextInterface
Chris@0 57 * The context object.
Chris@0 58 *
Chris@0 59 * @throws \Drupal\Component\Plugin\Exception\PluginException
Chris@0 60 * If the requested context is not set.
Chris@0 61 */
Chris@0 62 public function getContext($name);
Chris@0 63
Chris@0 64 /**
Chris@0 65 * Gets the values for all defined contexts.
Chris@0 66 *
Chris@0 67 * @return array
Chris@0 68 * An array of set context values, keyed by context name. If a context is
Chris@0 69 * unset its value is returned as NULL.
Chris@0 70 */
Chris@0 71 public function getContextValues();
Chris@0 72
Chris@0 73 /**
Chris@0 74 * Gets the value for a defined context.
Chris@0 75 *
Chris@0 76 * @param string $name
Chris@0 77 * The name of the context in the plugin configuration.
Chris@0 78 *
Chris@0 79 * @return mixed
Chris@0 80 * The currently set context value.
Chris@0 81 *
Chris@0 82 * @throws \Drupal\Component\Plugin\Exception\PluginException
Chris@0 83 * If the requested context is not set.
Chris@0 84 */
Chris@0 85 public function getContextValue($name);
Chris@0 86
Chris@0 87 /**
Chris@0 88 * Set a context on this plugin.
Chris@0 89 *
Chris@0 90 * @param string $name
Chris@0 91 * The name of the context in the plugin configuration.
Chris@0 92 * @param \Drupal\Component\Plugin\Context\ContextInterface $context
Chris@0 93 * The context object to set.
Chris@0 94 */
Chris@0 95 public function setContext($name, ContextInterface $context);
Chris@0 96
Chris@0 97 /**
Chris@0 98 * Sets the value for a defined context.
Chris@0 99 *
Chris@0 100 * @param string $name
Chris@0 101 * The name of the context in the plugin definition.
Chris@0 102 * @param mixed $value
Chris@0 103 * The value to set the context to. The value has to validate against the
Chris@0 104 * provided context definition.
Chris@0 105 *
Chris@0 106 * @return \Drupal\Component\Plugin\ContextAwarePluginInterface
Chris@0 107 * A context aware plugin object for chaining.
Chris@0 108 *
Chris@0 109 * @throws \Drupal\Component\Plugin\Exception\PluginException
Chris@0 110 * If the value does not pass validation.
Chris@0 111 */
Chris@0 112 public function setContextValue($name, $value);
Chris@0 113
Chris@0 114 /**
Chris@0 115 * Validates the set values for the defined contexts.
Chris@0 116 *
Chris@0 117 * @return \Symfony\Component\Validator\ConstraintViolationListInterface
Chris@0 118 * A list of constraint violations. If the list is empty, validation
Chris@0 119 * succeeded.
Chris@0 120 */
Chris@0 121 public function validateContexts();
Chris@0 122
Chris@0 123 /**
Chris@0 124 * Gets a mapping of the expected assignment names to their context names.
Chris@0 125 *
Chris@0 126 * @return array
Chris@0 127 * A mapping of the expected assignment names to their context names. For
Chris@0 128 * example, if one of the $contexts is named 'user.current_user', but the
Chris@0 129 * plugin expects a context named 'user', then this map would contain
Chris@0 130 * 'user' => 'user.current_user'.
Chris@0 131 */
Chris@0 132 public function getContextMapping();
Chris@0 133
Chris@0 134 /**
Chris@0 135 * Sets a mapping of the expected assignment names to their context names.
Chris@0 136 *
Chris@0 137 * @param array $context_mapping
Chris@0 138 * A mapping of the expected assignment names to their context names. For
Chris@0 139 * example, if one of the $contexts is named 'user.current_user', but the
Chris@0 140 * plugin expects a context named 'user', then this map would contain
Chris@0 141 * 'user' => 'user.current_user'.
Chris@0 142 *
Chris@0 143 * @return $this
Chris@0 144 */
Chris@0 145 public function setContextMapping(array $context_mapping);
Chris@0 146
Chris@0 147 }