Chris@0: <?php
Chris@0: 
Chris@0: namespace Drupal\Core\Field;
Chris@0: 
Chris@0: use Drupal\Core\Config\Entity\ConfigEntityInterface;
Chris@0: 
Chris@0: /**
Chris@0:  * Defines an interface for configurable field definitions.
Chris@0:  *
Chris@0:  * This interface allows both configurable fields and overridden base fields to
Chris@0:  * share a common interface. The interface also extends ConfigEntityInterface
Chris@0:  * to ensure that implementations have the expected save() method.
Chris@0:  *
Chris@0:  * @see \Drupal\Core\Field\Entity\BaseFieldOverride
Chris@0:  * @see \Drupal\field\Entity\FieldConfig
Chris@0:  */
Chris@0: interface FieldConfigInterface extends FieldDefinitionInterface, ConfigEntityInterface {
Chris@0: 
Chris@0:   /**
Chris@0:    * Sets the field definition label.
Chris@0:    *
Chris@0:    * @param string $label
Chris@0:    *   The label to set.
Chris@0:    *
Chris@0:    * @return $this
Chris@0:    */
Chris@0:   public function setLabel($label);
Chris@0: 
Chris@0:   /**
Chris@0:    * Sets a human readable description.
Chris@0:    *
Chris@0:    * Descriptions are usually used on user interfaces where the data is edited
Chris@0:    * or displayed.
Chris@0:    *
Chris@0:    * @param string $description
Chris@0:    *   The description for this field.
Chris@0:    *
Chris@0:    * @return $this
Chris@0:    */
Chris@0:   public function setDescription($description);
Chris@0: 
Chris@0:   /**
Chris@0:    * Sets whether the field is translatable.
Chris@0:    *
Chris@0:    * @param bool $translatable
Chris@0:    *   Whether the field is translatable.
Chris@0:    *
Chris@0:    * @return $this
Chris@0:    */
Chris@0:   public function setTranslatable($translatable);
Chris@0: 
Chris@0:   /**
Chris@0:    * Sets field settings.
Chris@0:    *
Chris@0:    * Note that the method does not unset existing settings not specified in the
Chris@0:    * incoming $settings array.
Chris@0:    *
Chris@0:    * For example:
Chris@0:    * @code
Chris@0:    *   // Given these are the default settings.
Chris@0:    *   $field_definition->getSettings() === [
Chris@0:    *     'fruit' => 'apple',
Chris@0:    *     'season' => 'summer',
Chris@0:    *   ];
Chris@0:    *   // Change only the 'fruit' setting.
Chris@0:    *   $field_definition->setSettings(['fruit' => 'banana']);
Chris@0:    *   // The 'season' setting persists unchanged.
Chris@0:    *   $field_definition->getSettings() === [
Chris@0:    *     'fruit' => 'banana',
Chris@0:    *     'season' => 'summer',
Chris@0:    *   ];
Chris@0:    * @endcode
Chris@0:    *
Chris@0:    * For clarity, it is preferred to use setSetting() if not all available
Chris@0:    * settings are supplied.
Chris@0:    *
Chris@0:    * @param array $settings
Chris@0:    *   The array of field settings.
Chris@0:    *
Chris@0:    * @return $this
Chris@0:    */
Chris@0:   public function setSettings(array $settings);
Chris@0: 
Chris@0:   /**
Chris@0:    * Sets the value for a field setting by name.
Chris@0:    *
Chris@0:    * @param string $setting_name
Chris@0:    *   The name of the setting.
Chris@0:    * @param mixed $value
Chris@0:    *   The value of the setting.
Chris@0:    *
Chris@0:    * @return $this
Chris@0:    */
Chris@0:   public function setSetting($setting_name, $value);
Chris@0: 
Chris@0:   /**
Chris@0:    * Sets whether the field can be empty.
Chris@0:    *
Chris@0:    * If a field is required, an entity needs to have at least a valid,
Chris@0:    * non-empty item in that field's FieldItemList in order to pass validation.
Chris@0:    *
Chris@0:    * An item is considered empty if its isEmpty() method returns TRUE.
Chris@0:    * Typically, that is if at least one of its required properties is empty.
Chris@0:    *
Chris@0:    * @param bool $required
Chris@0:    *   TRUE if the field is required. FALSE otherwise.
Chris@0:    *
Chris@0:    * @return $this
Chris@0:    *   The current object, for a fluent interface.
Chris@0:    */
Chris@0:   public function setRequired($required);
Chris@0: 
Chris@0:   /**
Chris@0:    * Sets a default value.
Chris@0:    *
Chris@0:    * Note that if a default value callback is set, it will take precedence over
Chris@0:    * any value set here.
Chris@0:    *
Chris@0:    * @param mixed $value
Chris@0:    *   The default value for the field. This can be either:
Chris@0:    *   - a literal, in which case it will be assigned to the first property of
Chris@0:    *     the first item.
Chris@0:    *   - a numerically indexed array of items, each item being a property/value
Chris@0:    *     array.
Chris@0:    *   - a non-numerically indexed array, in which case the array is assumed to
Chris@0:    *     be a property/value array and used as the first item
Chris@0:    *   - NULL or array() for no default value.
Chris@0:    *
Chris@0:    * @return $this
Chris@0:    */
Chris@0:   public function setDefaultValue($value);
Chris@0: 
Chris@0:   /**
Chris@0:    * Sets a custom default value callback.
Chris@0:    *
Chris@0:    * If set, the callback overrides any set default value.
Chris@0:    *
Chris@0:    * @param string|null $callback
Chris@0:    *   The callback to invoke for getting the default value (pass NULL to unset
Chris@0:    *   a previously set callback). The callback will be invoked with the
Chris@0:    *   following arguments:
Chris@0:    *   - \Drupal\Core\Entity\FieldableEntityInterface $entity
Chris@0:    *     The entity being created.
Chris@0:    *   - \Drupal\Core\Field\FieldDefinitionInterface $definition
Chris@0:    *     The field definition.
Chris@0:    *   It should return the default value in the format accepted by the
Chris@0:    *   setDefaultValue() method.
Chris@0:    *
Chris@0:    * @return $this
Chris@0:    */
Chris@0:   public function setDefaultValueCallback($callback);
Chris@0: 
Chris@0:   /**
Chris@0:    * Sets constraints for a given field item property.
Chris@0:    *
Chris@0:    * Note: this overwrites any existing property constraints. If you need to
Chris@0:    * add to the existing constraints, use
Chris@0:    * \Drupal\Core\Field\FieldConfigInterface::addPropertyConstraints()
Chris@0:    *
Chris@0:    * Note that constraints added via this method are not stored in configuration
Chris@0:    * and as such need to be added at runtime using
Chris@0:    * hook_entity_bundle_field_info_alter().
Chris@0:    *
Chris@0:    * @param string $name
Chris@0:    *   The name of the property to set constraints for.
Chris@0:    * @param array $constraints
Chris@0:    *   The constraints to set.
Chris@0:    *
Chris@0:    * @return static
Chris@0:    *   The object itself for chaining.
Chris@0:    *
Chris@0:    * @see hook_entity_bundle_field_info_alter()
Chris@0:    */
Chris@0:   public function setPropertyConstraints($name, array $constraints);
Chris@0: 
Chris@0:   /**
Chris@0:    * Adds constraints for a given field item property.
Chris@0:    *
Chris@0:    * Adds a constraint to a property of a field item. e.g.
Chris@0:    * @code
Chris@0:    * // Limit the field item's value property to the range 0 through 10.
Chris@0:    * // e.g. $node->field_how_many->value.
Chris@0:    * $field->addPropertyConstraints('value', [
Chris@0:    *   'Range' => [
Chris@0:    *     'min' => 0,
Chris@0:    *     'max' => 10,
Chris@0:    *   ]
Chris@0:    * ]);
Chris@0:    * @endcode
Chris@0:    *
Chris@0:    * If you want to add a validation constraint that applies to the
Chris@0:    * \Drupal\Core\Field\FieldItemList, use FieldConfigInterface::addConstraint()
Chris@0:    * instead.
Chris@0:    *
Chris@0:    * Note: passing a new set of options for an existing property constraint will
Chris@0:    * overwrite with the new options.
Chris@0:    *
Chris@0:    * Note that constraints added via this method are not stored in configuration
Chris@0:    * and as such need to be added at runtime using
Chris@0:    * hook_entity_bundle_field_info_alter().
Chris@0:    *
Chris@0:    * @param string $name
Chris@0:    *   The name of the property to set constraints for.
Chris@0:    * @param array $constraints
Chris@0:    *   The constraints to set.
Chris@0:    *
Chris@0:    * @return static
Chris@0:    *   The object itself for chaining.
Chris@0:    *
Chris@0:    * @see \Drupal\Core\Field\FieldConfigInterface::addConstraint()
Chris@0:    * @see hook_entity_bundle_field_info_alter()
Chris@0:    */
Chris@0:   public function addPropertyConstraints($name, array $constraints);
Chris@0: 
Chris@0:   /**
Chris@0:    * Adds a validation constraint to the FieldItemList.
Chris@0:    *
Chris@0:    * Note: If you wish to apply a constraint to just a property of a FieldItem
Chris@0:    * use \Drupal\Core\Field\FieldConfigInterface::addPropertyConstraints()
Chris@0:    * instead.
Chris@0:    * @code
Chris@0:    *   // Add a constraint to the 'field_username' FieldItemList.
Chris@0:    *   // e.g. $node->field_username
Chris@0:    *   $fields['field_username']->addConstraint('UniqueField');
Chris@0:    * @endcode
Chris@0:    *
Chris@0:    * If you wish to apply a constraint to a \Drupal\Core\Field\FieldItem instead
Chris@0:    * of a property or FieldItemList, you can use the
Chris@0:    * \Drupal\Core\Field\FieldConfigBase::getItemDefinition() method.
Chris@0:    * @code
Chris@0:    *   // Add a constraint to the 'field_entity_reference' FieldItem (entity
Chris@0:    *   // reference item).
Chris@0:    *   $fields['field_entity_reference']->getItemDefinition()->addConstraint('MyCustomFieldItemValidationPlugin', []);
Chris@0:    * @endcode
Chris@0:    *
Chris@0:    * See \Drupal\Core\TypedData\DataDefinitionInterface::getConstraints() for
Chris@0:    * details.
Chris@0:    *
Chris@0:    * Note that constraints added via this method are not stored in configuration
Chris@0:    * and as such need to be added at runtime using
Chris@0:    * hook_entity_bundle_field_info_alter().
Chris@0:    *
Chris@0:    * @param string $constraint_name
Chris@0:    *   The name of the constraint to add, i.e. its plugin id.
Chris@0:    * @param array|null $options
Chris@0:    *   The constraint options as required by the constraint plugin, or NULL.
Chris@0:    *
Chris@0:    * @return static
Chris@0:    *   The object itself for chaining.
Chris@0:    *
Chris@0:    * @see \Drupal\Core\Field\FieldItemList
Chris@0:    * @see \Drupal\Core\Field\FieldConfigInterface::addPropertyConstraints()
Chris@0:    * @see hook_entity_bundle_field_info_alter()
Chris@0:    */
Chris@0:   public function addConstraint($constraint_name, $options = NULL);
Chris@0: 
Chris@0:   /**
Chris@0:    * Sets the array of validation constraints for the FieldItemList.
Chris@0:    *
Chris@0:    * NOTE: This will overwrite any previously set constraints. In most cases
Chris@0:    * FieldConfigInterface::addConstraint() should be used instead.
Chris@0:    *
Chris@0:    * Note that constraints added via this method are not stored in configuration
Chris@0:    * and as such need to be added at runtime using
Chris@0:    * hook_entity_bundle_field_info_alter().
Chris@0:    *
Chris@0:    * @param array $constraints
Chris@0:    *   The array of constraints. See
Chris@0:    *   \Drupal\Core\TypedData\TypedDataManager::getConstraints() for details.
Chris@0:    *
Chris@0:    * @return $this
Chris@0:    *
Chris@0:    * @see \Drupal\Core\TypedData\DataDefinition::addConstraint()
Chris@0:    * @see \Drupal\Core\TypedData\DataDefinition::getConstraints()
Chris@0:    * @see \Drupal\Core\Field\FieldItemList
Chris@0:    * @see hook_entity_bundle_field_info_alter()
Chris@0:    */
Chris@0:   public function setConstraints(array $constraints);
Chris@0: 
Chris@0: }