FieldItemListInterface.php 8.34 KB
Newer Older
1
2
3
4
<?php

/**
 * @file
5
 * Contains \Drupal\Core\Field\FieldItemListInterface.
6
7
 */

8
namespace Drupal\Core\Field;
9

10
use Drupal\Core\Entity\FieldableEntityInterface;
11
use Drupal\Core\Form\FormStateInterface;
12
use Drupal\Core\Session\AccountInterface;
13
use Drupal\Core\Access\AccessibleInterface;
14
15
16
17
18
use Drupal\Core\TypedData\ListInterface;

/**
 * Interface for fields, being lists of field items.
 *
19
20
21
22
 * This interface must be implemented by every entity field, whereas contained
 * field items must implement the FieldItemInterface.
 * Some methods of the fields are delegated to the first contained item, in
 * particular get() and set() as well as their magic equivalences.
23
24
25
26
27
28
29
30
 *
 * Optionally, a typed data object implementing
 * Drupal\Core\TypedData\TypedDataInterface may be passed to
 * ArrayAccess::offsetSet() instead of a plain value.
 *
 * When implementing this interface which extends Traversable, make sure to list
 * IteratorAggregate or Iterator before this interface in the implements clause.
 */
31
interface FieldItemListInterface extends ListInterface, AccessibleInterface {
32

33
34
35
36
37
38
39
40
  /**
   * Gets the entity that field belongs to.
   *
   * @return \Drupal\Core\Entity\EntityInterface
   *   The entity object.
   */
  public function getEntity();

41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
  /**
   * Sets the langcode of the field values held in the object.
   *
   * @param string $langcode
   *   The langcode.
   */
  public function setLangcode($langcode);

  /**
   * Gets the langcode of the field values held in the object.
   *
   * @return $langcode
   *   The langcode.
   */
  public function getLangcode();

57
58
59
  /**
   * Gets the field definition.
   *
60
   * @return \Drupal\Core\Field\FieldDefinitionInterface
61
62
63
64
   *   The field definition.
   */
  public function getFieldDefinition();

65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
  /**
   * Returns the array of field settings.
   *
   * @return array
   *   An array of key/value pairs.
   */
  public function getSettings();

  /**
   * Returns the value of a given field setting.
   *
   * @param string $setting_name
   *   The setting name.
   *
   * @return mixed
   *   The setting value.
   */
  public function getSetting($setting_name);

84
85
86
  /**
   * Contains the default access logic of this field.
   *
87
   * See \Drupal\Core\Entity\EntityAccessControlHandlerInterface::fieldAccess() for
88
89
   * the parameter documentation.
   *
90
91
   * @return \Drupal\Core\Access\AccessResultInterface
   *   The access result.
92
93
94
   */
  public function defaultAccess($operation = 'view', AccountInterface $account = NULL);

95
96
  /**
   * Filters out empty field items and re-numbers the item deltas.
97
98
   *
   * @return $this
99
   */
100
  public function filterEmptyItems();
101

102
  /**
103
   * Magic method: Gets a property value of to the first field item.
104
   *
105
   * @see \Drupal\Core\Field\FieldItemInterface::__set()
106
107
108
109
   */
  public function __get($property_name);

  /**
110
   * Magic method: Sets a property value of the first field item.
111
   *
112
   * @see \Drupal\Core\Field\FieldItemInterface::__get()
113
114
115
116
   */
  public function __set($property_name, $value);

  /**
117
   * Magic method: Determines whether a property of the first field item is set.
118
   *
119
   * @see \Drupal\Core\Field\FieldItemInterface::__unset()
120
121
122
123
   */
  public function __isset($property_name);

  /**
124
   * Magic method: Unsets a property of the first field item.
125
   *
126
   * @see \Drupal\Core\Field\FieldItemInterface::__isset()
127
128
129
   */
  public function __unset($property_name);

130
131
132
  /**
   * Defines custom presave behavior for field values.
   *
133
134
135
136
   * This method is called during the process of saving an entity, just before
   * item values are written into storage.
   *
   * @see \Drupal\Core\Field\FieldItemInterface::preSave()
137
138
139
140
   */
  public function preSave();

  /**
141
   * Defines custom post-save behavior for field values.
142
   *
143
144
145
146
147
148
149
150
151
   * This method is called during the process of saving an entity, just after
   * item values are written into storage.
   *
   * @param bool $update
   *   Specifies whether the entity is being updated or created.
   *
   * @return bool
   *   Whether field items should be rewritten to the storage as a consequence
   *   of the logic implemented by the custom behavior.
152
   *
153
   * @see \Drupal\Core\Field\FieldItemInterface::postSave()
154
   */
155
  public function postSave($update);
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173

  /**
   * Defines custom delete behavior for field values.
   *
   * This method is called during the process of deleting an entity, just before
   * values are deleted from storage.
   */
  public function delete();

  /**
   * Defines custom revision delete behavior for field values.
   *
   * This method is called from during the process of deleting an entity
   * revision, just before the field values are deleted from storage. It is only
   * called for entity types that support revisioning.
   */
  public function deleteRevision();

174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
  /**
   * Returns a renderable array for the field items.
   *
   * @param array $display_options
   *   Can be either the name of a view mode, or an array of display settings.
   *   See EntityViewBuilderInterface::viewField() for more information.
   *
   * @return array
   *   A renderable array for the field values.
   *
   * @see \Drupal\Core\Entity\EntityViewBuilderInterface::viewField()
   * @see \Drupal\Core\Field\FieldItemInterface::view()
   */
  public function view($display_options = array());

189
190
191
192
193
194
195
196
  /*
   * Populates a specified number of field items with valid sample data.
   *
   * @param int $count
   *   The number of items to create.
   */
  public function generateSampleItems($count = 1);

197
198
199
  /**
   * Returns a form for the default value input.
   *
200
   * Invoked from \Drupal\field_ui\Form\FieldConfigEditForm to allow
201
202
203
204
   * administrators to configure instance-level default value.
   *
   * @param array $form
   *   The form where the settings form is being included in.
205
   * @param \Drupal\Core\Form\FormStateInterface $form_state
206
207
208
   *   The form state of the (entire) configuration form.
   *
   * @return array
209
   *   The form definition for the field default value.
210
   */
211
  public function defaultValuesForm(array &$form, FormStateInterface $form_state);
212
213
214
215

  /**
   * Validates the submitted default value.
   *
216
   * Invoked from \Drupal\field_ui\Form\FieldConfigEditForm to allow
217
218
219
220
221
222
   * administrators to configure instance-level default value.
   *
   * @param array $element
   *   The default value form element.
   * @param array $form
   *   The form where the settings form is being included in.
223
   * @param \Drupal\Core\Form\FormStateInterface $form_state
224
225
   *   The form state of the (entire) configuration form.
   */
226
  public function defaultValuesFormValidate(array $element, array &$form, FormStateInterface $form_state);
227
228
229
230

  /**
   * Processes the submitted default value.
   *
231
   * Invoked from \Drupal\field_ui\Form\FieldConfigEditForm to allow
232
233
234
235
236
237
   * administrators to configure instance-level default value.
   *
   * @param array $element
   *   The default value form element.
   * @param array $form
   *   The form where the settings form is being included in.
238
   * @param \Drupal\Core\Form\FormStateInterface $form_state
239
240
241
   *   The form state of the (entire) configuration form.
   *
   * @return array
242
   *   The field default value.
243
   */
244
  public function defaultValuesFormSubmit(array $element, array &$form, FormStateInterface $form_state);
245

246
247
248
249
  /**
   * Processes the default value before being applied.
   *
   * Defined or configured default values of a field might need some processing
250
251
   * in order to be a valid runtime value for the field type; e.g., a date field
   * could process the defined value of 'NOW' to a valid date.
252
   *
253
254
255
   * @param array
   *   The unprocessed default value defined for the field, as a numerically
   *   indexed array of items, each item being an array of property/value pairs.
256
   * @param \Drupal\Core\Entity\FieldableEntityInterface $entity
257
258
259
260
   *   The entity for which the default value is generated.
   * @param \Drupal\Core\Field\FieldDefinitionInterface $definition
   *   The definition of the field.
   *
261
262
   * @return array
   *   The return default value for the field.
263
   */
264
  public static function processDefaultValue($default_value, FieldableEntityInterface $entity, FieldDefinitionInterface $definition);
265

266
267
268
269
270
271
272
273
274
275
276
  /**
   * Determines equality to another object implementing FieldItemListInterface.
   *
   * @param \Drupal\Core\Field\FieldItemListInterface $list_to_compare
   *   The field item list to compare to.
   *
   * @return bool
   *   TRUE if the field item lists are equal, FALSE if not.
   */
  public function equals(FieldItemListInterface $list_to_compare);

277
}