www.aleph1.co.uk Git - yaffs-website/blob - web/core/lib/Drupal/Core/TypedData/TypedDataManagerInterface.php

   1 <?php
   2
   3 namespace Drupal\Core\TypedData;
   4
   5 use Drupal\Component\Plugin\PluginManagerInterface;
   6 use Drupal\Component\Plugin\Discovery\CachedDiscoveryInterface;
   7 use Drupal\Core\Validation\ConstraintManager;
   8 use Symfony\Component\Validator\Validator\ValidatorInterface;
   9
  10 /**
  11  * Defines an interface for typed data manager.
  12  */
  13 interface TypedDataManagerInterface extends PluginManagerInterface, CachedDiscoveryInterface {
  14
  15   /**
  16    * Instantiates a typed data object.
  17    *
  18    * @param string $data_type
  19    *   The data type, for which a typed object should be instantiated.
  20    * @param array $configuration
  21    *   The plugin configuration array, i.e. an array with the following keys:
  22    *   - data_definition: The data definition object, i.e. an instance of
  23    *     \Drupal\Core\TypedData\DataDefinitionInterface.
  24    *   - name: The name of the property or the delta of the list item if a
  25    *     property or list item is to be created. Otherwise, this should be set
  26    *     to NULL, but the key must be specified.
  27    *   - parent: The parent typed data object implementing either the
  28    *     ListInterface or the ComplexDataInterface if a property or list item is
  29    *     to be created. Otherwise, this should be set to NULL, but the key must
  30    *     be specified.
  31    *
  32    * @return \Drupal\Core\TypedData\TypedDataInterface
  33    *   The instantiated typed data object.
  34    *
  35    * @see \Drupal\Core\TypedData\TypedDataManager::create()
  36    */
  37   public function createInstance($data_type, array $configuration = []);
  38
  39   /**
  40    * Creates a new typed data object instance.
  41    *
  42    * @param \Drupal\Core\TypedData\DataDefinitionInterface $definition
  43    *   The data definition of the typed data object. For backwards-compatibility
  44    *   an array representation of the data definition may be passed also.
  45    * @param mixed $value
  46    *   (optional) The data value. If set, it has to match one of the supported
  47    *   data type format as documented for the data type classes.
  48    * @param string $name
  49    *   (optional) If a property or list item is to be created, the name of the
  50    *   property or the delta of the list item.
  51    * @param mixed $parent
  52    *   (optional) If a property or list item is to be created, the parent typed
  53    *   data object implementing either the ListInterface or the
  54    *   ComplexDataInterface.
  55    *
  56    * @return \Drupal\Core\TypedData\TypedDataInterface
  57    *   The instantiated typed data object.
  58    *
  59    * @see \Drupal\Core\TypedData\TypedDataManager::getPropertyInstance()
  60    * @see \Drupal\Core\TypedData\Plugin\DataType\BinaryData
  61    * @see \Drupal\Core\TypedData\Plugin\DataType\BooleanData
  62    * @see \Drupal\Core\TypedData\Plugin\DataType\Date
  63    * @see \Drupal\Core\TypedData\Plugin\DataType\Duration
  64    * @see \Drupal\Core\TypedData\Plugin\DataType\FloatData
  65    * @see \Drupal\Core\TypedData\Plugin\DataType\IntegerData
  66    * @see \Drupal\Core\TypedData\Plugin\DataType\StringData
  67    * @see \Drupal\Core\TypedData\Plugin\DataType\Uri
  68    */
  69   public function create(DataDefinitionInterface $definition, $value = NULL, $name = NULL, $parent = NULL);
  70
  71   /**
  72    * Creates a new data definition object.
  73    *
  74    * While data definitions objects may be created directly if the definition
  75    * class used by a data type is known, this method allows the creation of data
  76    * definitions for any given data type.
  77    *
  78    * For example, if a definition for a map is to be created, the following code
  79    * could be used instead of calling this method with the argument 'map':
  80    * @code
  81    *   $map_definition = \Drupal\Core\TypedData\MapDataDefinition::create();
  82    * @endcode
  83    *
  84    * @param string $data_type
  85    *   The data type plugin ID, for which a data definition object should be
  86    *   created.
  87    *
  88    * @return \Drupal\Core\TypedData\DataDefinitionInterface
  89    *   A data definition object for the given data type. The class of this
  90    *   object is provided by the definition_class in the plugin annotation.
  91    *
  92    * @see \Drupal\Core\TypedData\TypedDataManager::createListDataDefinition()
  93    */
  94   public function createDataDefinition($data_type);
  95
  96   /**
  97    * Creates a new list data definition for items of the given data type.
  98    *
  99    * @param string $item_type
 100    *   The item type, for which a list data definition should be created.
 101    *
 102    * @return \Drupal\Core\TypedData\ListDataDefinitionInterface
 103    *   A list definition for items of the given data type.
 104    *
 105    * @see \Drupal\Core\TypedData\TypedDataManager::createDataDefinition()
 106    */
 107   public function createListDataDefinition($item_type);
 108
 109   /**
 110    * {@inheritdoc}
 111    *
 112    * @param array $options
 113    *   An array of options with the following keys:
 114    *   - object: The parent typed data object, implementing the
 115    *     TypedDataInterface and either the ListInterface or the
 116    *     ComplexDataInterface.
 117    *   - property: The name of the property to instantiate, or the delta of the
 118    *     the list item to instantiate.
 119    *   - value: The value to set. If set, it has to match one of the supported
 120    *     data type formats as documented by the data type classes.
 121    *
 122    * @return \Drupal\Core\TypedData\TypedDataInterface
 123    *   The new property instance.
 124    *
 125    * @throws \InvalidArgumentException
 126    *   If the given property is not known, or the passed object does not
 127    *   implement the ListInterface or the ComplexDataInterface.
 128    *
 129    * @see \Drupal\Core\TypedData\TypedDataManager::getPropertyInstance()
 130    */
 131   public function getInstance(array $options);
 132
 133   /**
 134    * Get a typed data instance for a property of a given typed data object.
 135    *
 136    * This method will use prototyping for fast and efficient instantiation of
 137    * many property objects with the same property path; for example,
 138    * when multiple comments are used comment_body.0.value needs to be
 139    * instantiated very often.
 140    *
 141    * Prototyping is done by the root object's data type and the given
 142    * property path, i.e. all property instances having the same property path
 143    * and inheriting from the same data type are prototyped.
 144    *
 145    * @param \Drupal\Core\TypedData\TypedDataInterface $object
 146    *   The parent typed data object, implementing the TypedDataInterface and
 147    *   either the ListInterface or the ComplexDataInterface.
 148    * @param string $property_name
 149    *   The name of the property to instantiate, or the delta of an list item.
 150    * @param mixed $value
 151    *   (optional) The data value. If set, it has to match one of the supported
 152    *   data type formats as documented by the data type classes.
 153    *
 154    * @return \Drupal\Core\TypedData\TypedDataInterface
 155    *   The new property instance.
 156    *
 157    * @throws \InvalidArgumentException
 158    *   If the given property is not known, or the passed object does not
 159    *   implement the ListInterface or the ComplexDataInterface.
 160    *
 161    * @see \Drupal\Core\TypedData\TypedDataManager::create()
 162    */
 163   public function getPropertyInstance(TypedDataInterface $object, $property_name, $value = NULL);
 164
 165   /**
 166    * Gets the validator for validating typed data.
 167    *
 168    * @return \Symfony\Component\Validator\Validator\ValidatorInterface
 169    *   The validator object.
 170    */
 171   public function getValidator();
 172
 173   /**
 174    * Sets the validator for validating typed data.
 175    *
 176    * @param \Symfony\Component\Validator\Validator\ValidatorInterface $validator
 177    *   The validator object to set.
 178    */
 179   public function setValidator(ValidatorInterface $validator);
 180
 181   /**
 182    * Gets the validation constraint manager.
 183    *
 184    * @return \Drupal\Core\Validation\ConstraintManager
 185    *   The constraint manager.
 186    */
 187   public function getValidationConstraintManager();
 188
 189   /**
 190    * Sets the validation constraint manager.
 191    *
 192    * The validation constraint manager is used to instantiate validation
 193    * constraint plugins.
 194    *
 195    * @param \Drupal\Core\Validation\ConstraintManager $constraintManager
 196    *   The constraint manager to set.
 197    */
 198   public function setValidationConstraintManager(ConstraintManager $constraintManager);
 199
 200   /**
 201    * Gets default constraints for the given data definition.
 202    *
 203    * This generates default constraint definitions based on the data definition;
 204    * for example, a NotNull constraint is generated if the data is defined as
 205    * required. Besides that, any constraints defined for the data type (that is,
 206    * below the 'constraint' key of the type's plugin definition) are taken into
 207    * account.
 208    *
 209    * @param \Drupal\Core\TypedData\DataDefinitionInterface $definition
 210    *   A data definition.
 211    *
 212    * @return array
 213    *   An array of validation constraint definitions, keyed by constraint name.
 214    *   Each constraint definition can be used for instantiating
 215    *   \Symfony\Component\Validator\Constraint objects.
 216    */
 217   public function getDefaultConstraints(DataDefinitionInterface $definition);
 218
 219   /**
 220    * Gets the canonical representation of a TypedData object.
 221    *
 222    * The canonical representation is typically used when data is passed on to
 223    * other code components. In many use cases, the TypedData object is mostly
 224    * unified adapter wrapping a primary value (a string, an entity, etc.) which
 225    * is the canonical representation that consuming code like constraint
 226    * validators are really interested in. For some APIs, though, the domain
 227    * object (for example, Field API's FieldItem and FieldItemList) directly
 228    * implements TypedDataInterface, and the canonical representation is thus the
 229    * data object itself.
 230    *
 231    * When a TypedData object gets validated, for example, its canonical
 232    * representation is passed on to constraint validators, which thus receive
 233    * an Entity unwrapped, but a FieldItem as is.
 234    *
 235    * Data types specify whether their data objects need unwrapping by using the
 236    * 'unwrap_for_canonical_representation' property in the data definition
 237    * (defaults to TRUE).
 238    *
 239    * @param \Drupal\Core\TypedData\TypedDataInterface $data
 240    *   The data.
 241    *
 242    * @return mixed
 243    *   The canonical representation of the passed data.
 244    */
 245   public function getCanonicalRepresentation(TypedDataInterface $data);
 246
 247 }