1<?php
2
3namespace Drupal\Core\Field;
4
5use Drupal\Core\Config\Entity\ConfigEntityInterface;
6
7/**
8 * Defines an interface for configurable field definitions.
9 *
10 * This interface allows both configurable fields and overridden base fields to
11 * share a common interface. The interface also extends ConfigEntityInterface
12 * to ensure that implementations have the expected save() method.
13 *
14 * @see \Drupal\Core\Field\Entity\BaseFieldOverride
15 * @see \Drupal\field\Entity\FieldConfig
16 */
17interface FieldConfigInterface extends FieldDefinitionInterface, ConfigEntityInterface {
18
19  /**
20   * Sets the field definition label.
21   *
22   * @param string $label
23   *   The label to set.
24   *
25   * @return $this
26   */
27  public function setLabel($label);
28
29  /**
30   * Sets a human readable description.
31   *
32   * Descriptions are usually used on user interfaces where the data is edited
33   * or displayed.
34   *
35   * @param string $description
36   *   The description for this field.
37   *
38   * @return $this
39   */
40  public function setDescription($description);
41
42  /**
43   * Sets whether the field is translatable.
44   *
45   * @param bool $translatable
46   *   Whether the field is translatable.
47   *
48   * @return $this
49   */
50  public function setTranslatable($translatable);
51
52  /**
53   * Sets field settings.
54   *
55   * Note that the method does not unset existing settings not specified in the
56   * incoming $settings array.
57   *
58   * For example:
59   * @code
60   *   // Given these are the default settings.
61   *   $field_definition->getSettings() === [
62   *     'fruit' => 'apple',
63   *     'season' => 'summer',
64   *   ];
65   *   // Change only the 'fruit' setting.
66   *   $field_definition->setSettings(['fruit' => 'banana']);
67   *   // The 'season' setting persists unchanged.
68   *   $field_definition->getSettings() === [
69   *     'fruit' => 'banana',
70   *     'season' => 'summer',
71   *   ];
72   * @endcode
73   *
74   * For clarity, it is preferred to use setSetting() if not all available
75   * settings are supplied.
76   *
77   * @param array $settings
78   *   The array of field settings.
79   *
80   * @return $this
81   */
82  public function setSettings(array $settings);
83
84  /**
85   * Sets the value for a field setting by name.
86   *
87   * @param string $setting_name
88   *   The name of the setting.
89   * @param mixed $value
90   *   The value of the setting.
91   *
92   * @return $this
93   */
94  public function setSetting($setting_name, $value);
95
96  /**
97   * Sets whether the field can be empty.
98   *
99   * If a field is required, an entity needs to have at least a valid,
100   * non-empty item in that field's FieldItemList in order to pass validation.
101   *
102   * An item is considered empty if its isEmpty() method returns TRUE.
103   * Typically, that is if at least one of its required properties is empty.
104   *
105   * @param bool $required
106   *   TRUE if the field is required. FALSE otherwise.
107   *
108   * @return $this
109   *   The current object, for a fluent interface.
110   */
111  public function setRequired($required);
112
113  /**
114   * Sets a default value.
115   *
116   * Note that if a default value callback is set, it will take precedence over
117   * any value set here.
118   *
119   * @param mixed $value
120   *   The default value for the field. This can be either:
121   *   - a literal, in which case it will be assigned to the first property of
122   *     the first item.
123   *   - a numerically indexed array of items, each item being a property/value
124   *     array.
125   *   - a non-numerically indexed array, in which case the array is assumed to
126   *     be a property/value array and used as the first item
127   *   - NULL or array() for no default value.
128   *
129   * @return $this
130   */
131  public function setDefaultValue($value);
132
133  /**
134   * Sets a custom default value callback.
135   *
136   * If set, the callback overrides any set default value.
137   *
138   * @param string|null $callback
139   *   The callback to invoke for getting the default value (pass NULL to unset
140   *   a previously set callback). The callback will be invoked with the
141   *   following arguments:
142   *   - \Drupal\Core\Entity\FieldableEntityInterface $entity
143   *     The entity being created.
144   *   - \Drupal\Core\Field\FieldDefinitionInterface $definition
145   *     The field definition.
146   *   It should return the default value in the format accepted by the
147   *   setDefaultValue() method.
148   *
149   * @return $this
150   */
151  public function setDefaultValueCallback($callback);
152
153  /**
154   * Sets constraints for a given field item property.
155   *
156   * Note: this overwrites any existing property constraints. If you need to
157   * add to the existing constraints, use
158   * \Drupal\Core\Field\FieldConfigInterface::addPropertyConstraints()
159   *
160   * Note that constraints added via this method are not stored in configuration
161   * and as such need to be added at runtime using
162   * hook_entity_bundle_field_info_alter().
163   *
164   * @param string $name
165   *   The name of the property to set constraints for.
166   * @param array $constraints
167   *   The constraints to set.
168   *
169   * @return static
170   *   The object itself for chaining.
171   *
172   * @see hook_entity_bundle_field_info_alter()
173   */
174  public function setPropertyConstraints($name, array $constraints);
175
176  /**
177   * Adds constraints for a given field item property.
178   *
179   * Adds a constraint to a property of a field item. e.g.
180   * @code
181   * // Limit the field item's value property to the range 0 through 10.
182   * // e.g. $node->field_how_many->value.
183   * $field->addPropertyConstraints('value', [
184   *   'Range' => [
185   *     'min' => 0,
186   *     'max' => 10,
187   *   ]
188   * ]);
189   * @endcode
190   *
191   * If you want to add a validation constraint that applies to the
192   * \Drupal\Core\Field\FieldItemList, use FieldConfigInterface::addConstraint()
193   * instead.
194   *
195   * Note: passing a new set of options for an existing property constraint will
196   * overwrite with the new options.
197   *
198   * Note that constraints added via this method are not stored in configuration
199   * and as such need to be added at runtime using
200   * hook_entity_bundle_field_info_alter().
201   *
202   * @param string $name
203   *   The name of the property to set constraints for.
204   * @param array $constraints
205   *   The constraints to set.
206   *
207   * @return static
208   *   The object itself for chaining.
209   *
210   * @see \Drupal\Core\Field\FieldConfigInterface::addConstraint()
211   * @see hook_entity_bundle_field_info_alter()
212   */
213  public function addPropertyConstraints($name, array $constraints);
214
215  /**
216   * Adds a validation constraint to the FieldItemList.
217   *
218   * Note: If you wish to apply a constraint to just a property of a FieldItem
219   * use \Drupal\Core\Field\FieldConfigInterface::addPropertyConstraints()
220   * instead.
221   * @code
222   *   // Add a constraint to the 'field_username' FieldItemList.
223   *   // e.g. $node->field_username
224   *   $fields['field_username']->addConstraint('UniqueField');
225   * @endcode
226   *
227   * If you wish to apply a constraint to a \Drupal\Core\Field\FieldItem instead
228   * of a property or FieldItemList, you can use the
229   * \Drupal\Core\Field\FieldConfigBase::getItemDefinition() method.
230   * @code
231   *   // Add a constraint to the 'field_entity_reference' FieldItem (entity
232   *   // reference item).
233   *   $fields['field_entity_reference']->getItemDefinition()->addConstraint('MyCustomFieldItemValidationPlugin', []);
234   * @endcode
235   *
236   * See \Drupal\Core\TypedData\DataDefinitionInterface::getConstraints() for
237   * details.
238   *
239   * Note that constraints added via this method are not stored in configuration
240   * and as such need to be added at runtime using
241   * hook_entity_bundle_field_info_alter().
242   *
243   * @param string $constraint_name
244   *   The name of the constraint to add, i.e. its plugin id.
245   * @param array|null $options
246   *   The constraint options as required by the constraint plugin, or NULL.
247   *
248   * @return static
249   *   The object itself for chaining.
250   *
251   * @see \Drupal\Core\Field\FieldItemList
252   * @see \Drupal\Core\Field\FieldConfigInterface::addPropertyConstraints()
253   * @see hook_entity_bundle_field_info_alter()
254   */
255  public function addConstraint($constraint_name, $options = NULL);
256
257  /**
258   * Sets the array of validation constraints for the FieldItemList.
259   *
260   * NOTE: This will overwrite any previously set constraints. In most cases
261   * FieldConfigInterface::addConstraint() should be used instead.
262   *
263   * Note that constraints added via this method are not stored in configuration
264   * and as such need to be added at runtime using
265   * hook_entity_bundle_field_info_alter().
266   *
267   * @param array $constraints
268   *   The array of constraints. See
269   *   \Drupal\Core\TypedData\TypedDataManager::getConstraints() for details.
270   *
271   * @return $this
272   *
273   * @see \Drupal\Core\TypedData\DataDefinition::addConstraint()
274   * @see \Drupal\Core\TypedData\DataDefinition::getConstraints()
275   * @see \Drupal\Core\Field\FieldItemList
276   * @see hook_entity_bundle_field_info_alter()
277   */
278  public function setConstraints(array $constraints);
279
280}
281