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

   1 <?php
   2
   3 namespace Drupal\Core\TypedData;
   4
   5 /**
   6  * Interface for data definitions.
   7  *
   8  * Data definitions are used to describe data based upon available data types.
   9  * For example, a plugin could describe its parameters using data definitions
  10  * in order to specify what kind of data is required for it.
  11  *
  12  * Definitions that describe lists or complex data have to implement the
  13  * respective interfaces, such that the metadata about contained list items or
  14  * properties can be retrieved from the definition.
  15  *
  16  * @see \Drupal\Core\TypedData\DataDefinition
  17  * @see \Drupal\Core\TypedData\ListDefinitionInterface
  18  * @see \Drupal\Core\TypedData\ComplexDataDefinitionInterface
  19  * @see \Drupal\Core\TypedData\DataReferenceDefinitionInterface
  20  * @see \Drupal\Core\TypedData\TypedDataInterface
  21  *
  22  * @ingroup typed_data
  23  */
  24 interface DataDefinitionInterface {
  25
  26   /**
  27    * Creates a new data definition object.
  28    *
  29    * This method is typically used by
  30    * \Drupal\Core\TypedData\TypedDataManager::createDataDefinition() to build a
  31    * definition object for an arbitrary data type. When the definition class is
  32    * known, it is recommended to directly use the static create() method on that
  33    * class instead; e.g.:
  34    * @code
  35    *   $map_definition = \Drupal\Core\TypedData\MapDataDefinition::create();
  36    * @endcode
  37    *
  38    * @param string $data_type
  39    *   The data type, for which a data definition should be created.
  40    *
  41    * @return static
  42    *
  43    * @throws \InvalidArgumentException
  44    *   If an unsupported data type gets passed to the class; e.g., 'string' to a
  45    *   definition class handling 'entity:* data types.
  46    */
  47   public static function createFromDataType($data_type);
  48
  49   /**
  50    * Returns the data type of the data.
  51    *
  52    * @return string
  53    *   The data type.
  54    */
  55   public function getDataType();
  56
  57   /**
  58    * Returns a human readable label.
  59    *
  60    * @return string|\Drupal\Core\StringTranslation\TranslatableMarkup
  61    *   The label. A string or an instance of TranslatableMarkup will be returned
  62    *   based on the way the label translation is handled.
  63    */
  64   public function getLabel();
  65
  66   /**
  67    * Returns a human readable description.
  68    *
  69    * Descriptions are usually used on user interfaces where the data is edited
  70    * or displayed.
  71    *
  72    * @return string|null
  73    *   The description, or NULL if no description is available.
  74    */
  75   public function getDescription();
  76
  77   /**
  78    * Returns whether the data is multi-valued, i.e. a list of data items.
  79    *
  80    * This is equivalent to checking whether the data definition implements the
  81    * \Drupal\Core\TypedData\ListDefinitionInterface interface.
  82    *
  83    * @return bool
  84    *   Whether the data is multi-valued.
  85    */
  86   public function isList();
  87
  88   /**
  89    * Determines whether the data is read-only.
  90    *
  91    * @return bool
  92    *   Whether the data is read-only.
  93    */
  94   public function isReadOnly();
  95
  96   /**
  97    * Determines whether the data value is computed.
  98    *
  99    * For example, data could be computed depending on some other values.
 100    *
 101    * @return bool
 102    *   Whether the data value is computed.
 103    */
 104   public function isComputed();
 105
 106   /**
 107    * Determines whether a data value is required.
 108    *
 109    * For required data a non-NULL value is mandatory.
 110    *
 111    * @return bool
 112    *   Whether a data value is required.
 113    */
 114   public function isRequired();
 115
 116   /**
 117    * Returns the class used for creating the typed data object.
 118    *
 119    * If not specified, the default class of the data type will be returned.
 120    *
 121    * @return string
 122    *   The class used for creating the typed data object.
 123    */
 124   public function getClass();
 125
 126   /**
 127    * Returns the array of settings, as required by the used class.
 128    *
 129    * See the documentation of the class for supported or required settings.
 130    *
 131    * @return array
 132    *   The array of settings.
 133    */
 134   public function getSettings();
 135
 136   /**
 137    * Returns the value of a given setting.
 138    *
 139    * @param string $setting_name
 140    *   The setting name.
 141    *
 142    * @return mixed
 143    *   The setting value.
 144    */
 145   public function getSetting($setting_name);
 146
 147   /**
 148    * Returns an array of validation constraints.
 149    *
 150    * The validation constraints of a definition consist of any for it defined
 151    * constraints and default constraints, which are generated based on the
 152    * definition and its data type. See
 153    * \Drupal\Core\TypedData\TypedDataManager::getDefaultConstraints().
 154    *
 155    * Constraints are defined via an array, having constraint plugin IDs as key
 156    * and constraint options as values, e.g.
 157    * @code
 158    * $constraints = array(
 159    *   'Range' => array('min' => 5, 'max' => 10),
 160    *   'NotBlank' => array(),
 161    * );
 162    * @endcode
 163    * Options have to be specified using another array if the constraint has more
 164    * than one or zero options. If it has exactly one option, the value should be
 165    * specified without nesting it into another array:
 166    * @code
 167    * $constraints = array(
 168    *   'EntityType' => 'node',
 169    *   'Bundle' => 'article',
 170    * );
 171    * @endcode
 172    *
 173    * Note that the specified constraints must be compatible with the data type,
 174    * e.g. for data of type 'entity' the 'EntityType' and 'Bundle' constraints
 175    * may be specified.
 176    *
 177    * @see \Drupal\Core\Validation\ConstraintManager
 178    *
 179    * @return array[]
 180    *   An array of validation constraint definitions, keyed by constraint name.
 181    *   Each constraint definition can be used for instantiating
 182    *   \Symfony\Component\Validator\Constraint objects.
 183    *
 184    * @see \Symfony\Component\Validator\Constraint
 185    */
 186   public function getConstraints();
 187
 188   /**
 189    * Returns a validation constraint.
 190    *
 191    * See \Drupal\Core\TypedData\DataDefinitionInterface::getConstraints() for
 192    * details.
 193    *
 194    * @param string $constraint_name
 195    *   The name of the constraint, i.e. its plugin id.
 196    *
 197    * @return array
 198    *   A validation constraint definition which can be used for instantiating a
 199    *   \Symfony\Component\Validator\Constraint object.
 200    *
 201    * @see \Symfony\Component\Validator\Constraint
 202    */
 203   public function getConstraint($constraint_name);
 204
 205   /**
 206    * Adds a validation constraint.
 207    *
 208    * See \Drupal\Core\TypedData\DataDefinitionInterface::getConstraints() for
 209    * details.
 210    *
 211    * @param string $constraint_name
 212    *   The name of the constraint to add, i.e. its plugin id.
 213    * @param array|null $options
 214    *   The constraint options as required by the constraint plugin, or NULL.
 215    *
 216    * @return static
 217    *   The object itself for chaining.
 218    */
 219   public function addConstraint($constraint_name, $options = NULL);
 220
 221 }