3 namespace Drupal\Core\Field;
5 use Drupal\Core\Config\Entity\ConfigEntityInterface;
8 * Defines an interface for configurable field definitions.
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.
14 * @see \Drupal\Core\Field\Entity\BaseFieldOverride
15 * @see \Drupal\field\Entity\FieldConfig
17 interface FieldConfigInterface extends FieldDefinitionInterface, ConfigEntityInterface {
20 * Sets the field definition label.
22 * @param string $label
27 public function setLabel($label);
30 * Sets a human readable description.
32 * Descriptions are usually used on user interfaces where the data is edited
35 * @param string $description
36 * The description for this field.
40 public function setDescription($description);
43 * Sets whether the field is translatable.
45 * @param bool $translatable
46 * Whether the field is translatable.
50 public function setTranslatable($translatable);
53 * Sets field settings.
55 * Note that the method does not unset existing settings not specified in the
56 * incoming $settings array.
60 * // Given these are the default settings.
61 * $field_definition->getSettings() === [
63 * 'season' => 'summer',
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',
74 * For clarity, it is preferred to use setSetting() if not all available
75 * settings are supplied.
77 * @param array $settings
78 * The array of field settings.
82 public function setSettings(array $settings);
85 * Sets the value for a field setting by name.
87 * @param string $setting_name
88 * The name of the setting.
90 * The value of the setting.
94 public function setSetting($setting_name, $value);
97 * Sets whether the field can be empty.
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.
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.
105 * @param bool $required
106 * TRUE if the field is required. FALSE otherwise.
109 * The current object, for a fluent interface.
111 public function setRequired($required);
114 * Sets a default value.
116 * Note that if a default value callback is set, it will take precedence over
117 * any value set here.
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
123 * - a numerically indexed array of items, each item being a property/value
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.
131 public function setDefaultValue($value);
134 * Sets a custom default value callback.
136 * If set, the callback overrides any set default value.
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.
151 public function setDefaultValueCallback($callback);
154 * Sets constraints for a given field item property.
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()
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().
164 * @param string $name
165 * The name of the property to set constraints for.
166 * @param array $constraints
167 * The constraints to set.
170 * The object itself for chaining.
172 * @see hook_entity_bundle_field_info_alter()
174 public function setPropertyConstraints($name, array $constraints);
177 * Adds constraints for a given field item property.
179 * Adds a constraint to a property of a field item. e.g.
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', [
191 * If you want to add a validation constraint that applies to the
192 * \Drupal\Core\Field\FieldItemList, use FieldConfigInterface::addConstraint()
195 * Note: passing a new set of options for an existing property constraint will
196 * overwrite with the new options.
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().
202 * @param string $name
203 * The name of the property to set constraints for.
204 * @param array $constraints
205 * The constraints to set.
208 * The object itself for chaining.
210 * @see \Drupal\Core\Field\FieldConfigInterface::addConstraint()
211 * @see hook_entity_bundle_field_info_alter()
213 public function addPropertyConstraints($name, array $constraints);
216 * Adds a validation constraint to the FieldItemList.
218 * Note: If you wish to apply a constraint to just a property of a FieldItem
219 * use \Drupal\Core\Field\FieldConfigInterface::addPropertyConstraints()
222 * // Add a constraint to the 'field_username' FieldItemList.
223 * // e.g. $node->field_username
224 * $fields['field_username']->addConstraint('UniqueField');
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.
231 * // Add a constraint to the 'field_entity_reference' FieldItem (entity
232 * // reference item).
233 * $fields['field_entity_reference']->getItemDefinition()->addConstraint('MyCustomFieldItemValidationPlugin', []);
236 * See \Drupal\Core\TypedData\DataDefinitionInterface::getConstraints() for
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().
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.
249 * The object itself for chaining.
251 * @see \Drupal\Core\Field\FieldItemList
252 * @see \Drupal\Core\Field\FieldConfigInterface::addPropertyConstraints()
253 * @see hook_entity_bundle_field_info_alter()
255 public function addConstraint($constraint_name, $options = NULL);
258 * Sets the array of validation constraints for the FieldItemList.
260 * NOTE: This will overwrite any previously set constraints. In most cases
261 * FieldConfigInterface::addConstraint() should be used instead.
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().
267 * @param array $constraints
268 * The array of constraints. See
269 * \Drupal\Core\TypedData\TypedDataManager::getConstraints() for details.
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()
278 public function setConstraints(array $constraints);