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 storage is revisionable.
 101    *
 102    * Note that if the entity type is revisionable and the field storage has a
 103    * cardinality higher than 1, the field storage is considered revisionable
 104    * by default.
 105    *
 106    * @return bool
 107    *   TRUE if the field is revisionable.
 108    */
 109   public function isRevisionable();
 110
 111   /**
 112    * Determines whether the field is queryable via QueryInterface.
 113    *
 114    * @return bool
 115    *   TRUE if the field is queryable.
 116    *
 117    * @deprecated in Drupal 8.4.0 and will be removed before Drupal 9.0.0. Use
 118    *   \Drupal\Core\Field\FieldStorageDefinitionInterface::hasCustomStorage()
 119    *   instead.
 120    *
 121    * @see https://www.drupal.org/node/2856563
 122    */
 123   public function isQueryable();
 124
 125   /**
 126    * Returns the human-readable label for the field.
 127    *
 128    * @return string
 129    *   The field label.
 130    */
 131   public function getLabel();
 132
 133   /**
 134    * Returns the human-readable description for the field.
 135    *
 136    * This is displayed in addition to the label in places where additional
 137    * descriptive information is helpful. For example, as help text below the
 138    * form element in entity edit forms.
 139    *
 140    * @return string|null
 141    *   The field description, or NULL if no description is available.
 142    */
 143   public function getDescription();
 144
 145   /**
 146    * Gets an options provider for the given field item property.
 147    *
 148    * @param string $property_name
 149    *   The name of the property to get options for; e.g., 'value'.
 150    * @param \Drupal\Core\Entity\FieldableEntityInterface $entity
 151    *   The entity for which the options should be provided.
 152    *
 153    * @return \Drupal\Core\TypedData\OptionsProviderInterface|null
 154    *   An options provider, or NULL if no options are defined.
 155    */
 156   public function getOptionsProvider($property_name, FieldableEntityInterface $entity);
 157
 158   /**
 159    * Returns whether the field can contain multiple items.
 160    *
 161    * @return bool
 162    *   TRUE if the field can contain multiple items, FALSE otherwise.
 163    */
 164   public function isMultiple();
 165
 166   /**
 167    * Returns the maximum number of items allowed for the field.
 168    *
 169    * Possible values are positive integers or
 170    * FieldStorageDefinitionInterface::CARDINALITY_UNLIMITED.
 171    *
 172    * @return int
 173    *   The field cardinality.
 174    */
 175   public function getCardinality();
 176
 177   /**
 178    * Gets the definition of a contained property.
 179    *
 180    * @param string $name
 181    *   The name of property.
 182    *
 183    * @return \Drupal\Core\TypedData\DataDefinitionInterface|null
 184    *   The definition of the property or NULL if the property does not exist.
 185    */
 186   public function getPropertyDefinition($name);
 187
 188   /**
 189    * Gets an array of property definitions of contained properties.
 190    *
 191    * @return \Drupal\Core\TypedData\DataDefinitionInterface[]
 192    *   An array of property definitions of contained properties, keyed by
 193    *   property name.
 194    */
 195   public function getPropertyDefinitions();
 196
 197   /**
 198    * Returns the names of the field's subproperties.
 199    *
 200    * A field is a list of items, and each item can contain one or more
 201    * properties. All items for a given field contain the same property names,
 202    * but the values can be different for each item.
 203    *
 204    * For example, an email field might just contain a single 'value' property,
 205    * while a link field might contain 'title' and 'url' properties, and a text
 206    * field might contain 'value', 'summary', and 'format' properties.
 207    *
 208    * @return string[]
 209    *   The property names.
 210    */
 211   public function getPropertyNames();
 212
 213   /**
 214    * Returns the name of the main property, if any.
 215    *
 216    * Some field items consist mainly of one main property, e.g. the value of a
 217    * text field or the @code target_id @endcode of an entity reference. If the
 218    * field item has no main property, the method returns NULL.
 219    *
 220    * @return string|null
 221    *   The name of the value property, or NULL if there is none.
 222    */
 223   public function getMainPropertyName();
 224
 225   /**
 226    * Returns the ID of the entity type the field is attached to.
 227    *
 228    * This method should not be confused with EntityInterface::getEntityTypeId()
 229    * (configurable fields are config entities, and thus implement both
 230    * interfaces):
 231    *   - FieldStorageDefinitionInterface::getTargetEntityTypeId() answers "as a
 232    *     field storage, which entity type are you attached to?".
 233    *   - EntityInterface::getEntityTypeId() answers "as a (config) entity, what
 234    *     is your own entity type?".
 235    *
 236    * @return string
 237    *   The entity type ID.
 238    */
 239   public function getTargetEntityTypeId();
 240
 241   /**
 242    * Returns the field schema.
 243    *
 244    * Note that this method returns an empty array for computed fields which have
 245    * no schema.
 246    *
 247    * @return array[]
 248    *   The field schema, as an array of key/value pairs in the format returned
 249    *   by \Drupal\Core\Field\FieldItemInterface::schema():
 250    *   - columns: An array of Schema API column specifications, keyed by column
 251    *     name. This specifies what comprises a single value for a given field.
 252    *     No assumptions should be made on how storage backends internally use
 253    *     the original column name to structure their storage.
 254    *   - indexes: An array of Schema API index definitions. Some storage
 255    *     backends might not support indexes.
 256    *   - unique keys: An array of Schema API unique key definitions.  Some
 257    *     storage backends might not support unique keys.
 258    *   - foreign keys: An array of Schema API foreign key definitions. Note,
 259    *     however, that depending on the storage backend specified for the field,
 260    *     the field data is not necessarily stored in SQL.
 261    */
 262   public function getSchema();
 263
 264   /**
 265    * Returns the field columns, as defined in the field schema.
 266    *
 267    * @return array[]
 268    *   The array of field columns, keyed by column name, in the same format
 269    *   returned by getSchema().
 270    *
 271    * @see \Drupal\Core\Field\FieldStorageDefinitionInterface::getSchema()
 272    */
 273   public function getColumns();
 274
 275   /**
 276    * Returns an array of validation constraints.
 277    *
 278    * See \Drupal\Core\TypedData\DataDefinitionInterface::getConstraints() for
 279    * details.
 280    *
 281    * @return array[]
 282    *   An array of validation constraint definitions, keyed by constraint name.
 283    *   Each constraint definition can be used for instantiating
 284    *   \Symfony\Component\Validator\Constraint objects.
 285    *
 286    * @see \Symfony\Component\Validator\Constraint
 287    */
 288   public function getConstraints();
 289
 290   /**
 291    * Returns a validation constraint.
 292    *
 293    * See \Drupal\Core\TypedData\DataDefinitionInterface::getConstraints() for
 294    * details.
 295    *
 296    * @param string $constraint_name
 297    *   The name of the constraint, i.e. its plugin id.
 298    *
 299    * @return array
 300    *   A validation constraint definition which can be used for instantiating a
 301    *   \Symfony\Component\Validator\Constraint object.
 302    *
 303    * @see \Symfony\Component\Validator\Constraint
 304    */
 305   public function getConstraint($constraint_name);
 306
 307   /**
 308    * Returns the name of the provider of this field.
 309    *
 310    * @return string
 311    *   The provider name; e.g., the module name.
 312    */
 313   public function getProvider();
 314
 315   /**
 316    * Returns the storage behavior for this field.
 317    *
 318    * Indicates whether the entity type's storage should take care of storing the
 319    * field values or whether it is handled separately; e.g. by the
 320    * module providing the field.
 321    *
 322    * @return bool
 323    *   FALSE if the storage takes care of storing the field, TRUE otherwise.
 324    */
 325   public function hasCustomStorage();
 326
 327   /**
 328    * Determines whether the field is a base field.
 329    *
 330    * Base fields are not specific to a given bundle or a set of bundles. This
 331    * excludes configurable fields, as they are always attached to a specific
 332    * bundle.
 333    *
 334    * @return bool
 335    *   Whether the field is a base field.
 336    */
 337   public function isBaseField();
 338
 339   /**
 340    * Returns a unique identifier for the field storage.
 341    *
 342    * @return string
 343    */
 344   public function getUniqueStorageIdentifier();
 345
 346   /**
 347    * Returns whether the field is deleted or not.
 348    *
 349    * @return bool
 350    *   TRUE if the field is deleted, FALSE otherwise.
 351    */
 352   public function isDeleted();
 353
 354 }