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