FieldItemListInterface.php 9.28 KB
Newer Older
1 2
<?php

3
namespace Drupal\Core\Field;
4

5
use Drupal\Core\Entity\FieldableEntityInterface;
6
use Drupal\Core\Form\FormStateInterface;
7
use Drupal\Core\Session\AccountInterface;
8
use Drupal\Core\Access\AccessibleInterface;
9 10 11 12 13
use Drupal\Core\TypedData\ListInterface;

/**
 * Interface for fields, being lists of field items.
 *
14 15 16 17
 * 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.
18 19 20 21 22 23 24
 *
 * 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.
25 26
 *
 * @see \Drupal\Core\Field\FieldItemInterface
27
 */
28
interface FieldItemListInterface extends ListInterface, AccessibleInterface {
29

30 31 32
  /**
   * Gets the entity that field belongs to.
   *
33
   * @return \Drupal\Core\Entity\FieldableEntityInterface
34 35 36 37
   *   The entity object.
   */
  public function getEntity();

38 39 40 41 42 43 44 45 46 47 48
  /**
   * 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.
   *
49
   * @return string
50 51 52 53
   *   The langcode.
   */
  public function getLangcode();

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

62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80
  /**
   * 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);

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

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

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

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

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

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

127 128 129
  /**
   * Defines custom presave behavior for field values.
   *
130 131 132 133
   * 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()
134 135 136 137
   */
  public function preSave();

  /**
138
   * Defines custom post-save behavior for field values.
139
   *
140 141 142 143 144 145 146 147 148
   * 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.
149
   *
150
   * @see \Drupal\Core\Field\FieldItemInterface::postSave()
151
   */
152
  public function postSave($update);
153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170

  /**
   * 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();

171 172 173 174 175 176 177 178 179 180 181 182 183
  /**
   * 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()
   */
184
  public function view($display_options = []);
185

186
  /**
187 188 189 190 191 192 193
   * 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);

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

  /**
   * Validates the submitted default value.
   *
213
   * Invoked from \Drupal\field_ui\Form\FieldConfigEditForm to allow
214 215 216 217 218 219
   * 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.
220
   * @param \Drupal\Core\Form\FormStateInterface $form_state
221 222
   *   The form state of the (entire) configuration form.
   */
223
  public function defaultValuesFormValidate(array $element, array &$form, FormStateInterface $form_state);
224 225 226 227

  /**
   * Processes the submitted default value.
   *
228
   * Invoked from \Drupal\field_ui\Form\FieldConfigEditForm to allow
229 230 231 232 233 234
   * 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.
235
   * @param \Drupal\Core\Form\FormStateInterface $form_state
236 237 238
   *   The form state of the (entire) configuration form.
   *
   * @return array
239
   *   The field default value.
240
   */
241
  public function defaultValuesFormSubmit(array $element, array &$form, FormStateInterface $form_state);
242

243 244 245 246
  /**
   * Processes the default value before being applied.
   *
   * Defined or configured default values of a field might need some processing
247 248
   * 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.
249
   *
250
   * @param array $default_value
251 252
   *   The unprocessed default value defined for the field, as a numerically
   *   indexed array of items, each item being an array of property/value pairs.
253
   * @param \Drupal\Core\Entity\FieldableEntityInterface $entity
254 255 256 257
   *   The entity for which the default value is generated.
   * @param \Drupal\Core\Field\FieldDefinitionInterface $definition
   *   The definition of the field.
   *
258 259
   * @return array
   *   The return default value for the field.
260
   */
261
  public static function processDefaultValue($default_value, FieldableEntityInterface $entity, FieldDefinitionInterface $definition);
262

263 264 265
  /**
   * Determines equality to another object implementing FieldItemListInterface.
   *
266 267 268
   * This method is usually used by the storage to check for not computed
   * value changes, which will be saved into the storage.
   *
269 270 271 272 273 274 275 276
   * @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 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296
  /**
   * Determines whether the field has relevant changes.
   *
   * This is for example used to determine if a revision of an entity has
   * changes in a given translation. Unlike
   * \Drupal\Core\Field\FieldItemListInterface::equals(), this can report
   * that for example an untranslatable field, despite being changed and
   * therefore technically affecting all translations, is only internal metadata
   * or only affects a single translation.
   *
   * @param \Drupal\Core\Field\FieldItemListInterface $original_items
   *   The original field items to compare against.
   * @param string $langcode
   *   The language that should be checked.
   *
   * @return bool
   *   TRUE if the field has relevant changes, FALSE if not.
   */
  public function hasAffectingChanges(FieldItemListInterface $original_items, $langcode);

297
}