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