3 namespace Drupal\Core\Field;
5 use Drupal\Core\Cache\CacheableDependencyInterface;
6 use Drupal\Core\Entity\FieldableEntityInterface;
7 use Drupal\Core\TypedData\ListDataDefinitionInterface;
10 * Defines an interface for entity field definitions.
12 * An entity field is a data object that holds the values of a particular field
13 * for a particular entity (see \Drupal\Core\Field\FieldItemListInterface). For
14 * example, $node_1->body and $node_2->body contain different data and therefore
15 * are different field objects.
17 * In contrast, an entity field *definition* is an object that returns
18 * information *about* a field (e.g., its type and settings) rather than its
19 * values. As such, if all the information about $node_1->body and $node_2->body
20 * is the same, then the same field definition object can be used to describe
23 * It is up to the class implementing this interface to manage where the
24 * information comes from. For example, field.module provides an implementation
25 * based on two levels of configuration. It allows the site administrator to add
26 * custom fields to any entity type and bundle via the "field_storage_config"
27 * and "field_config" configuration entities. The former for storing
28 * configuration that is independent of which entity type and bundle the field
29 * is added to, and the latter for storing configuration that is specific to the
30 * entity type and bundle. The class that implements "field_config"
31 * configuration entities also implements this interface, returning information
32 * from either itself, or from the corresponding "field_storage_config"
33 * configuration, as appropriate.
35 * However, entity base fields, such as $node->title, are not managed by
36 * field.module and its "field_storage_config"/"field_config"
37 * configuration entities. Therefore, their definitions are provided by
38 * different objects based on the class \Drupal\Core\Field\BaseFieldDefinition,
39 * which implements this interface as well.
41 * Field definitions may fully define a concrete data object (e.g.,
42 * $node_1->body), or may provide a best-guess definition for a data object that
43 * might come into existence later. For example, $node_1->body and $node_2->body
44 * may have different definitions (e.g., if the node types are different). When
45 * adding the "body" field to a View that can return nodes of different types,
46 * the View can get a field definition that represents the "body" field
47 * abstractly, and present Views configuration options to the administrator
48 * based on that abstract definition, even though that abstract definition can
49 * differ from the concrete definition of any particular node's body field.
51 interface FieldDefinitionInterface extends ListDataDefinitionInterface, CacheableDependencyInterface {
54 * Returns the machine name of the field.
56 * This defines how the field data is accessed from the entity. For example,
57 * if the field name is "foo", then $entity->foo returns its data.
62 public function getName();
65 * Returns the field type.
68 * The field type, i.e. the id of a field type plugin. For example 'text'.
70 * @see \Drupal\Core\Field\FieldTypePluginManagerInterface
72 public function getType();
75 * Returns the ID of the entity type the field is attached to.
77 * This method should not be confused with EntityInterface::getEntityTypeId()
78 * (configurable fields are config entities, and thus implement both
80 * - FieldDefinitionInterface::getTargetEntityTypeId() answers "as a field,
81 * which entity type are you attached to?".
82 * - EntityInterface::getEntityTypeId() answers "as a (config) entity, what
83 * is your own entity type?".
88 public function getTargetEntityTypeId();
91 * Gets the bundle the field is attached to.
93 * This method should not be confused with EntityInterface::bundle()
94 * (configurable fields are config entities, and thus implement both
96 * - FieldDefinitionInterface::getTargetBundle() answers "as a field,
97 * which bundle are you attached to?".
98 * - EntityInterface::bundle() answers "as a (config) entity, what
99 * is your own bundle?" (not relevant in our case, the config entity types
100 * used to store the definitions of configurable fields do not have
103 * @return string|null
104 * The bundle the field is defined for, or NULL if it is a base field; i.e.,
105 * it is not bundle-specific.
107 public function getTargetBundle();
110 * Returns whether the display for the field can be configured.
112 * @param string $display_context
113 * The display context. Either 'view' or 'form'.
116 * TRUE if the display for this field is configurable in the given context.
117 * If TRUE, the display options returned by getDisplayOptions() may be
118 * overridden via the respective entity display.
120 * @see \Drupal\Core\Entity\Display\EntityDisplayInterface
122 public function isDisplayConfigurable($display_context);
125 * Returns the default display options for the field.
127 * If the field's display is configurable, the returned display options act
128 * as default values and may be overridden via the respective entity display.
129 * Otherwise, the display options will be applied to entity displays as is.
131 * @param string $display_context
132 * The display context. Either 'view' or 'form'.
135 * The array of display options for the field, or NULL if the field is not
136 * displayed. The following key/value pairs may be present:
137 * - label: (string) Position of the field label. The default 'field' theme
138 * implementation supports the values 'inline', 'above' and 'hidden'.
139 * Defaults to 'above'. Only applies to 'view' context.
140 * - region: (string) The region the field is in, or 'hidden'. If not
141 * specified, the default region will be used.
142 * - type: (string) The plugin (widget or formatter depending on
143 * $display_context) to use. If not specified or if the requested plugin
144 * is unknown, the 'default_widget' / 'default_formatter' for the field
145 * type will be used. Previously 'hidden' was a valid value, it is now
146 * deprecated in favor of specifying 'region' => 'hidden'.
147 * - settings: (array) Settings for the plugin specified above. The default
148 * settings for the plugin will be used for settings left unspecified.
149 * - third_party_settings: (array) Settings provided by other extensions
150 * through hook_field_formatter_third_party_settings_form().
151 * - weight: (float) The weight of the element. Not needed if 'type' is
153 * The defaults of the various display options above get applied by the used
156 * @see \Drupal\Core\Entity\Display\EntityDisplayInterface
158 public function getDisplayOptions($display_context);
161 * Returns whether the field can be empty.
163 * If a field is required, an entity needs to have at least a valid,
164 * non-empty item in that field's FieldItemList in order to pass validation.
166 * An item is considered empty if its isEmpty() method returns TRUE.
167 * Typically, that is if at least one of its required properties is empty.
170 * TRUE if the field is required.
172 * @see \Drupal\Core\TypedData\Plugin\DataType\ItemList::isEmpty()
173 * @see \Drupal\Core\Field\FieldItemInterface::isEmpty()
174 * @see \Drupal\Core\TypedData\DataDefinitionInterface:isRequired()
175 * @see \Drupal\Core\TypedData\TypedDataManager::getDefaultConstraints()
177 public function isRequired();
180 * Returns the default value literal for the field.
182 * This method retrieves the raw property assigned to the field definition.
183 * When computing the runtime default value for a field in a given entity,
184 * ::getDefaultValue() should be used instead.
187 * The default value for the field, as a numerically indexed array of items,
188 * each item being a property/value array (array() for no default value).
190 * @see FieldDefinitionInterface::getDefaultValue()
191 * @see FieldDefinitionInterface::getDefaultValueCallback()
193 public function getDefaultValueLiteral();
196 * Returns the default value callback for the field.
198 * This method retrieves the raw property assigned to the field definition.
199 * When computing the runtime default value for a field in a given entity,
200 * ::getDefaultValue() should be used instead.
202 * @return string|null
203 * The default value callback for the field.
205 * @see FieldDefinitionInterface::getDefaultValue()
206 * @see FieldDefinitionInterface::getDefaultValueLiteral()
208 public function getDefaultValueCallback();
211 * Returns the default value for the field in a newly created entity.
213 * This method computes the runtime default value for a field in a given
214 * entity. To access the raw properties assigned to the field definition,
215 * ::getDefaultValueLiteral() or ::getDefaultValueCallback() should be used
218 * @param \Drupal\Core\Entity\FieldableEntityInterface $entity
219 * The entity for which the default value is generated.
222 * The default value for the field, as a numerically indexed array of items,
223 * each item being a property/value array (array() for no default value).
225 * @see FieldDefinitionInterface::getDefaultValueLiteral()
226 * @see FieldDefinitionInterface::getDefaultValueCallback()
228 public function getDefaultValue(FieldableEntityInterface $entity);
231 * Returns whether the field is translatable.
234 * TRUE if the field is translatable.
236 public function isTranslatable();
239 * Returns the field storage definition.
241 * @return \Drupal\Core\Field\FieldStorageDefinitionInterface
242 * The field storage definition.
244 public function getFieldStorageDefinition();
247 * Gets an object that can be saved in configuration.
249 * Base fields are defined in code. In order to configure field definition
250 * properties per bundle use this method to create an override that can be
251 * saved in configuration.
253 * @see \Drupal\Core\Field\Entity\BaseFieldBundleOverride
255 * @param string $bundle
256 * The bundle to get the configurable field for.
258 * @return \Drupal\Core\Field\FieldConfigInterface
260 public function getConfig($bundle);
263 * Returns a unique identifier for the field.
267 public function getUniqueIdentifier();