annotate core/lib/Drupal/Core/Field/FieldConfigInterface.php @ 19:fa3358dc1485 tip

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