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

   1 <?php
   2
   3 namespace Drupal\Core\Field;
   4
   5 use Drupal\Core\Cache\CacheableDependencyInterface;
   6 use Drupal\Core\Entity\FieldableEntityInterface;
   7
   8 /**
   9  * Defines an interface for entity field storage definitions.
  10  *
  11  * Field storage definitions represent the part of full field definitions (see
  12  * FieldDefinitionInterface) that is responsible for defining how the field is
  13  * stored. While field definitions may differ by entity bundle, all of those
  14  * bundle fields have to share the same common field storage definition. Thus,
  15  * the storage definitions can be defined by entity type only.
  16  * The bundle fields corresponding to a field storage definition may provide
  17  * additional information; e.g., they may provide bundle-specific settings or
  18  * constraints that are not present in the storage definition. However bundle
  19  * fields may not override or alter any information provided by the storage
  20  * definition except for the label and the description; e.g., any constraints
  21  * and settings on the storage definition must be present on the bundle field as
  22  * well.
  23  *
  24  * @see hook_entity_field_storage_info()
  25  */
  26 interface FieldStorageDefinitionInterface extends CacheableDependencyInterface {
  27
  28   /**
  29    * Value indicating a field accepts an unlimited number of values.
  30    */
  31   const CARDINALITY_UNLIMITED = -1;
  32
  33   /**
  34    * Returns the machine name of the field.
  35    *
  36    * This defines how the field data is accessed from the entity. For example,
  37    * if the field name is "foo", then $entity->foo returns its data.
  38    *
  39    * @return string
  40    *   The field name.
  41    */
  42   public function getName();
  43
  44   /**
  45    * Returns the field type.
  46    *
  47    * @return string
  48    *   The field type, i.e. the id of a field type plugin. For example 'text'.
  49    *
  50    * @see \Drupal\Core\Field\FieldTypePluginManagerInterface
  51    */
  52   public function getType();
  53
  54   /**
  55    * Returns the storage settings.
  56    *
  57    * Each field type defines the settings that are meaningful for that type.
  58    * For example, a text field can define a 'max_length' setting, and an image
  59    * field can define a 'alt_field_required' setting.
  60    *
  61    * The method always returns an array of all available settings for this field
  62    * type, possibly with the default values merged in if values have not been
  63    * provided for all available settings.
  64    *
  65    * @return mixed[]
  66    *   An array of key/value pairs.
  67    */
  68   public function getSettings();
  69
  70   /**
  71    * Returns the value of a given storage setting.
  72    *
  73    * @param string $setting_name
  74    *   The setting name.
  75    *
  76    * @return mixed
  77    *   The setting value.
  78    */
  79   public function getSetting($setting_name);
  80
  81   /**
  82    * Returns whether the field supports translation.
  83    *
  84    * @return bool
  85    *   TRUE if the field supports translation.
  86    */
  87   public function isTranslatable();
  88
  89   /**
  90    * Sets whether the field supports translation.
  91    *
  92    * @param bool $translatable
  93    *   Whether the field supports translation.
  94    *
  95    * @return $this
  96    */
  97   public function setTranslatable($translatable);
  98
  99   /**
 100    * Returns whether the field is revisionable.
 101    *
 102    * @return bool
 103    *   TRUE if the field is revisionable.
 104    */
 105   public function isRevisionable();
 106
 107   /**
 108    * Determines whether the field is queryable via QueryInterface.
 109    *
 110    * @return bool
 111    *   TRUE if the field is queryable.
 112    *
 113    * @deprecated in Drupal 8.4.0 and will be removed before Drupal 9.0.0. Use
 114    *   \Drupal\Core\Field\FieldStorageDefinitionInterface::hasCustomStorage()
 115    *   instead.
 116    *
 117    * @see https://www.drupal.org/node/2856563
 118    */
 119   public function isQueryable();
 120
 121   /**
 122    * Returns the human-readable label for the field.
 123    *
 124    * @return string
 125    *   The field label.
 126    */
 127   public function getLabel();
 128
 129   /**
 130    * Returns the human-readable description for the field.
 131    *
 132    * This is displayed in addition to the label in places where additional
 133    * descriptive information is helpful. For example, as help text below the
 134    * form element in entity edit forms.
 135    *
 136    * @return string|null
 137    *   The field description, or NULL if no description is available.
 138    */
 139   public function getDescription();
 140
 141   /**
 142    * Gets an options provider for the given field item property.
 143    *
 144    * @param string $property_name
 145    *   The name of the property to get options for; e.g., 'value'.
 146    * @param \Drupal\Core\Entity\FieldableEntityInterface $entity
 147    *   The entity for which the options should be provided.
 148    *
 149    * @return \Drupal\Core\TypedData\OptionsProviderInterface|null
 150    *   An options provider, or NULL if no options are defined.
 151    */
 152   public function getOptionsProvider($property_name, FieldableEntityInterface $entity);
 153
 154   /**
 155    * Returns whether the field can contain multiple items.
 156    *
 157    * @return bool
 158    *   TRUE if the field can contain multiple items, FALSE otherwise.
 159    */
 160   public function isMultiple();
 161
 162   /**
 163    * Returns the maximum number of items allowed for the field.
 164    *
 165    * Possible values are positive integers or
 166    * FieldStorageDefinitionInterface::CARDINALITY_UNLIMITED.
 167    *
 168    * @return int
 169    *   The field cardinality.
 170    */
 171   public function getCardinality();
 172
 173   /**
 174    * Gets the definition of a contained property.
 175    *
 176    * @param string $name
 177    *   The name of property.
 178    *
 179    * @return \Drupal\Core\TypedData\DataDefinitionInterface|null
 180    *   The definition of the property or NULL if the property does not exist.
 181    */
 182   public function getPropertyDefinition($name);
 183
 184   /**
 185    * Gets an array of property definitions of contained properties.
 186    *
 187    * @return \Drupal\Core\TypedData\DataDefinitionInterface[]
 188    *   An array of property definitions of contained properties, keyed by
 189    *   property name.
 190    */
 191   public function getPropertyDefinitions();
 192
 193   /**
 194    * Returns the names of the field's subproperties.
 195    *
 196    * A field is a list of items, and each item can contain one or more
 197    * properties. All items for a given field contain the same property names,
 198    * but the values can be different for each item.
 199    *
 200    * For example, an email field might just contain a single 'value' property,
 201    * while a link field might contain 'title' and 'url' properties, and a text
 202    * field might contain 'value', 'summary', and 'format' properties.
 203    *
 204    * @return string[]
 205    *   The property names.
 206    */
 207   public function getPropertyNames();
 208
 209   /**
 210    * Returns the name of the main property, if any.
 211    *
 212    * Some field items consist mainly of one main property, e.g. the value of a
 213    * text field or the @code target_id @endcode of an entity reference. If the
 214    * field item has no main property, the method returns NULL.
 215    *
 216    * @return string|null
 217    *   The name of the value property, or NULL if there is none.
 218    */
 219   public function getMainPropertyName();
 220
 221   /**
 222    * Returns the ID of the entity type the field is attached to.
 223    *
 224    * This method should not be confused with EntityInterface::getEntityTypeId()
 225    * (configurable fields are config entities, and thus implement both
 226    * interfaces):
 227    *   - FieldStorageDefinitionInterface::getTargetEntityTypeId() answers "as a
 228    *     field storage, which entity type are you attached to?".
 229    *   - EntityInterface::getEntityTypeId() answers "as a (config) entity, what
 230    *     is your own entity type?".
 231    *
 232    * @return string
 233    *   The entity type ID.
 234    */
 235   public function getTargetEntityTypeId();
 236
 237   /**
 238    * Returns the field schema.
 239    *
 240    * Note that this method returns an empty array for computed fields which have
 241    * no schema.
 242    *
 243    * @return array[]
 244    *   The field schema, as an array of key/value pairs in the format returned
 245    *   by \Drupal\Core\Field\FieldItemInterface::schema():
 246    *   - columns: An array of Schema API column specifications, keyed by column
 247    *     name. This specifies what comprises a single value for a given field.
 248    *     No assumptions should be made on how storage backends internally use
 249    *     the original column name to structure their storage.
 250    *   - indexes: An array of Schema API index definitions. Some storage
 251    *     backends might not support indexes.
 252    *   - unique keys: An array of Schema API unique key definitions.  Some
 253    *     storage backends might not support unique keys.
 254    *   - foreign keys: An array of Schema API foreign key definitions. Note,
 255    *     however, that depending on the storage backend specified for the field,
 256    *     the field data is not necessarily stored in SQL.
 257    */
 258   public function getSchema();
 259
 260   /**
 261    * Returns the field columns, as defined in the field schema.
 262    *
 263    * @return array[]
 264    *   The array of field columns, keyed by column name, in the same format
 265    *   returned by getSchema().
 266    *
 267    * @see \Drupal\Core\Field\FieldStorageDefinitionInterface::getSchema()
 268    */
 269   public function getColumns();
 270
 271   /**
 272    * Returns an array of validation constraints.
 273    *
 274    * See \Drupal\Core\TypedData\DataDefinitionInterface::getConstraints() for
 275    * details.
 276    *
 277    * @return array[]
 278    *   An array of validation constraint definitions, keyed by constraint name.
 279    *   Each constraint definition can be used for instantiating
 280    *   \Symfony\Component\Validator\Constraint objects.
 281    *
 282    * @see \Symfony\Component\Validator\Constraint
 283    */
 284   public function getConstraints();
 285
 286   /**
 287    * Returns a validation constraint.
 288    *
 289    * See \Drupal\Core\TypedData\DataDefinitionInterface::getConstraints() for
 290    * details.
 291    *
 292    * @param string $constraint_name
 293    *   The name of the constraint, i.e. its plugin id.
 294    *
 295    * @return array
 296    *   A validation constraint definition which can be used for instantiating a
 297    *   \Symfony\Component\Validator\Constraint object.
 298    *
 299    * @see \Symfony\Component\Validator\Constraint
 300    */
 301   public function getConstraint($constraint_name);
 302
 303   /**
 304    * Returns the name of the provider of this field.
 305    *
 306    * @return string
 307    *   The provider name; e.g., the module name.
 308    */
 309   public function getProvider();
 310
 311   /**
 312    * Returns the storage behavior for this field.
 313    *
 314    * Indicates whether the entity type's storage should take care of storing the
 315    * field values or whether it is handled separately; e.g. by the
 316    * module providing the field.
 317    *
 318    * @return bool
 319    *   FALSE if the storage takes care of storing the field, TRUE otherwise.
 320    */
 321   public function hasCustomStorage();
 322
 323   /**
 324    * Determines whether the field is a base field.
 325    *
 326    * Base fields are not specific to a given bundle or a set of bundles. This
 327    * excludes configurable fields, as they are always attached to a specific
 328    * bundle.
 329    *
 330    * @return bool
 331    *   Whether the field is a base field.
 332    */
 333   public function isBaseField();
 334
 335   /**
 336    * Returns a unique identifier for the field.
 337    *
 338    * @return string
 339    */
 340   public function getUniqueStorageIdentifier();
 341
 342 }