aleph1.co.uk Git - yaffs-website/blob - web/core/lib/Drupal/Core/Field/FieldConfigInterface.php

   1 <?php
   2
   3 namespace Drupal\Core\Field;
   4
   5 use 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  */
  17 interface 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 }