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

   1 <?php
   2
   3 namespace Drupal\Core\TypedData;
   4
   5 /**
   6  * Interface for typed data objects.
   7  *
   8  * @see \Drupal\Core\TypedData\DataDefinitionInterface
   9  *
  10  * @ingroup typed_data
  11  */
  12 interface TypedDataInterface {
  13
  14   /**
  15    * Constructs a TypedData object given its definition and context.
  16    *
  17    * @param \Drupal\Core\TypedData\DataDefinitionInterface $definition
  18    *   The data definition.
  19    * @param string|null $name
  20    *   (optional) The name of the created property, or NULL if it is the root
  21    *   of a typed data tree. Defaults to NULL.
  22    * @param \Drupal\Core\TypedData\TraversableTypedDataInterface $parent
  23    *   (optional) The parent object of the data property, or NULL if it is the
  24    *   root of a typed data tree. Defaults to NULL.
  25    *
  26    * @todo When \Drupal\Core\Config\TypedConfigManager has been fixed to use
  27    *   class-based definitions, type-hint $definition to
  28    *   DataDefinitionInterface. https://www.drupal.org/node/1928868
  29    *
  30    * @see \Drupal\Core\TypedData\TypedDataManager::create()
  31    */
  32   public static function createInstance($definition, $name = NULL, TraversableTypedDataInterface $parent = NULL);
  33
  34   /**
  35    * Gets the data definition.
  36    *
  37    * @return \Drupal\Core\TypedData\DataDefinitionInterface
  38    *   The data definition object.
  39    */
  40   public function getDataDefinition();
  41
  42   /**
  43    * Gets the data value.
  44    *
  45    * @return mixed
  46    */
  47   public function getValue();
  48
  49   /**
  50    * Sets the data value.
  51    *
  52    * @param mixed|null $value
  53    *   The value to set in the format as documented for the data type or NULL to
  54    *   unset the data value.
  55    * @param bool $notify
  56    *   (optional) Whether to notify the parent object of the change. Defaults to
  57    *   TRUE. If a property is updated from a parent object, set it to FALSE to
  58    *   avoid being notified again.
  59    *
  60    * @throws \InvalidArgumentException
  61    *   If the value input is inappropriate.
  62    * @throws \Drupal\Core\TypedData\Exception\ReadOnlyException
  63    *   If the data is read-only.
  64    */
  65   public function setValue($value, $notify = TRUE);
  66
  67   /**
  68    * Returns a string representation of the data.
  69    *
  70    * @return string
  71    */
  72   public function getString();
  73
  74   /**
  75    * Gets a list of validation constraints.
  76    *
  77    * @return array
  78    *   Array of constraints, each being an instance of
  79    *   \Symfony\Component\Validator\Constraint.
  80    */
  81   public function getConstraints();
  82
  83   /**
  84    * Validates the currently set data value.
  85    *
  86    * @return \Symfony\Component\Validator\ConstraintViolationListInterface
  87    *   A list of constraint violations. If the list is empty, validation
  88    *   succeeded.
  89    */
  90   public function validate();
  91
  92   /**
  93    * Applies the default value.
  94    *
  95    * @param bool $notify
  96    *   (optional) Whether to notify the parent object of the change. Defaults to
  97    *   TRUE. If a property is updated from a parent object, set it to FALSE to
  98    *   avoid being notified again.
  99    *
 100    * @return \Drupal\Core\TypedData\TypedDataInterface
 101    *   Returns itself to allow for chaining.
 102    */
 103   public function applyDefaultValue($notify = TRUE);
 104
 105   /**
 106    * Returns the name of a property or item.
 107    *
 108    * @return string
 109    *   If the data is a property of some complex data, the name of the property.
 110    *   If the data is an item of a list, the name is the numeric position of the
 111    *   item in the list, starting with 0. Otherwise, NULL is returned.
 112    */
 113   public function getName();
 114
 115   /**
 116    * Returns the parent data structure; i.e. either complex data or a list.
 117    *
 118    * @return \Drupal\Core\TypedData\TraversableTypedDataInterface|null
 119    *   The parent data structure, either complex data or a list; or NULL if this
 120    *   is the root of the typed data tree.
 121    */
 122   public function getParent();
 123
 124   /**
 125    * Returns the root of the typed data tree.
 126    *
 127    * Returns the root data for a tree of typed data objects; e.g. for an entity
 128    * field item the root of the tree is its parent entity object.
 129    *
 130    * @return \Drupal\Core\TypedData\TraversableTypedDataInterface
 131    *   The root data structure, either complex data or a list.
 132    */
 133   public function getRoot();
 134
 135   /**
 136    * Returns the property path of the data.
 137    *
 138    * The trail of property names relative to the root of the typed data tree,
 139    * separated by dots; e.g. 'field_text.0.format'.
 140    *
 141    * @return string
 142    *   The property path relative to the root of the typed tree, or an empty
 143    *   string if this is the root.
 144    */
 145   public function getPropertyPath();
 146
 147   /**
 148    * Sets the context of a property or item via a context aware parent.
 149    *
 150    * This method is supposed to be called by the factory only.
 151    *
 152    * @param string|null $name
 153    *   (optional) The name of the property or the delta of the list item,
 154    *   or NULL if it is the root of a typed data tree. Defaults to NULL.
 155    * @param \Drupal\Core\TypedData\TraversableTypedDataInterface|null $parent
 156    *   (optional) The parent object of the data property, or NULL if it is the
 157    *   root of a typed data tree. Defaults to NULL.
 158    */
 159   public function setContext($name = NULL, TraversableTypedDataInterface $parent = NULL);
 160
 161 }