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