FieldConfigBase.php

<?php

namespace Drupal\Core\Field;

use Drupal\Core\Config\Action\Attribute\ActionMethod;
use Drupal\Core\Config\Entity\ConfigEntityBase;
use Drupal\Core\Entity\EntityStorageInterface;
use Drupal\Core\Entity\FieldableEntityInterface;
use Drupal\Core\Field\TypedData\FieldItemDataDefinition;
use Drupal\Core\StringTranslation\TranslatableMarkup;

/**
 * Base class for configurable field definitions.
 */
abstract class FieldConfigBase extends ConfigEntityBase implements FieldConfigInterface {
    use FieldInputValueNormalizerTrait;
    
    /**
     * The field ID.
     *
     * The ID consists of 3 parts: the entity type, bundle and the field name.
     *
     * Example: node.article.body, user.user.field_main_image.
     *
     * @var string
     */
    protected $id;
    
    /**
     * The field name.
     *
     * @var string
     */
    protected $field_name;
    
    /**
     * The field type.
     *
     * This property is denormalized from the field storage for optimization of
     * the "entity and render cache hits" critical paths. If not present in the
     * $values passed to create(), it is populated from the field storage in
     * postCreate(), and saved in config records so that it is present on
     * subsequent loads.
     *
     * @var string
     */
    protected $field_type;
    
    /**
     * The name of the entity type the field is attached to.
     *
     * @var string
     */
    protected $entity_type;
    
    /**
     * The name of the bundle the field is attached to.
     *
     * @var string
     */
    protected $bundle;
    
    /**
     * The human-readable label for the field.
     *
     * This will be used as the title of Form API elements for the field in entity
     * edit forms, or as the label for the field values in displayed entities.
     *
     * If not specified, this defaults to the field_name (mostly useful for fields
     * created in tests).
     *
     * @var string
     */
    protected $label;
    
    /**
     * The field description.
     *
     * A human-readable description for the field when used with this bundle.
     * For example, the description will be the help text of Form API elements for
     * this field in entity edit forms.
     *
     * @var string
     */
    protected $description = '';
    
    /**
     * Field-type specific settings.
     *
     * An array of key/value pairs. The keys and default values are defined by the
     * field type.
     *
     * @var array
     */
    protected $settings = [];
    
    /**
     * Flag indicating whether the field is required.
     *
     * TRUE if a value for this field is required when used with this bundle,
     * FALSE otherwise. Currently, required-ness is only enforced at the Form API
     * level in entity edit forms, not during direct API saves.
     *
     * @var bool
     */
    protected $required = FALSE;
    
    /**
     * Flag indicating whether the field is translatable.
     *
     * Defaults to TRUE.
     *
     * @var bool
     */
    protected $translatable = TRUE;
    
    /**
     * Default field value.
     *
     * The default value is used when an entity is created, either:
     * - through an entity creation form; the form elements for the field are
     *   prepopulated with the default value.
     * - through direct API calls (i.e. $entity->save()); the default value is
     *   added if the $entity object provides no explicit entry (actual values or
     *   "the field is empty") for the field.
     *
     * The default value is expressed as a numerically indexed array of items,
     * each item being an array of key/value pairs matching the set of 'columns'
     * defined by the "field schema" for the field type, as exposed in the class
     * implementing \Drupal\Core\Field\FieldItemInterface::schema() method. If the
     * number of items exceeds the cardinality of the field, extraneous items will
     * be ignored.
     *
     * This property is overlooked if the $default_value_callback is non-empty.
     *
     * Example for an integer field:
     * @code
     * [
     *   ['value' => 1],
     *   ['value' => 2],
     * ]
     * @endcode
     *
     * @var array
     */
    protected $default_value = [];
    
    /**
     * The name of a callback function that returns default values.
     *
     * The function will be called with the following arguments:
     * - \Drupal\Core\Entity\FieldableEntityInterface $entity
     *   The entity being created.
     * - \Drupal\Core\Field\FieldDefinitionInterface $definition
     *   The field definition.
     * It should return an array of default values, in the same format as the
     * $default_value property.
     *
     * This property takes precedence on the list of fixed values specified in the
     * $default_value property.
     *
     * @var string
     */
    protected $default_value_callback = '';
    
    /**
     * The field storage object.
     *
     * @var \Drupal\Core\Field\FieldStorageDefinitionInterface
     */
    protected $fieldStorage;
    
    /**
     * The data definition of a field item.
     *
     * @var \Drupal\Core\Field\TypedData\FieldItemDataDefinition
     */
    protected $itemDefinition;
    
    /**
     * Array of constraint options keyed by constraint plugin ID.
     *
     * @var array
     */
    protected $constraints = [];
    
    /**
     * Array of property constraint options keyed by property ID.
     *
     * The values are associative array of constraint options keyed by constraint
     * plugin ID.
     *
     * @var array[]
     */
    protected $propertyConstraints = [];
    
    /**
     * {@inheritdoc}
     */
    public function id() {
        return $this->entity_type . '.' . $this->bundle . '.' . $this->field_name;
    }
    
    /**
     * {@inheritdoc}
     */
    public function getName() {
        return $this->field_name;
    }
    
    /**
     * {@inheritdoc}
     */
    public function getType() {
        return $this->field_type;
    }
    
    /**
     * {@inheritdoc}
     */
    public function getTargetEntityTypeId() {
        return $this->entity_type;
    }
    
    /**
     * {@inheritdoc}
     */
    public function getTargetBundle() {
        return $this->bundle;
    }
    
    /**
     * {@inheritdoc}
     */
    public function calculateDependencies() {
        parent::calculateDependencies();
        // Add dependencies from the field type plugin. We can not use
        // self::calculatePluginDependencies() because instantiation of a field item
        // plugin requires a parent entity.
        
        /** @var \Drupal\Core\Field\FieldTypePluginManagerInterface $field_type_manager */
        $field_type_manager = \Drupal::service('plugin.manager.field.field_type');
        $definition = $field_type_manager->getDefinition($this->getType());
        $this->addDependency('module', $definition['provider']);
        // Plugins can declare additional dependencies in their definition.
        if (isset($definition['config_dependencies'])) {
            $this->addDependencies($definition['config_dependencies']);
        }
        // Let the field type plugin specify its own dependencies.
        // @see \Drupal\Core\Field\FieldItemInterface::calculateDependencies()
        $this->addDependencies($definition['class']::calculateDependencies($this));
        // Create dependency on the bundle.
        $bundle_config_dependency = $this->entityTypeManager()
            ->getDefinition($this->entity_type)
            ->getBundleConfigDependency($this->bundle);
        $this->addDependency($bundle_config_dependency['type'], $bundle_config_dependency['name']);
        return $this;
    }
    
    /**
     * {@inheritdoc}
     */
    public function onDependencyRemoval(array $dependencies) {
        $changed = parent::onDependencyRemoval($dependencies);
        $field_type_manager = \Drupal::service('plugin.manager.field.field_type');
        $definition = $field_type_manager->getDefinition($this->getType());
        if ($definition['class']::onDependencyRemoval($this, $dependencies)) {
            $changed = TRUE;
        }
        return $changed;
    }
    
    /**
     * {@inheritdoc}
     */
    public function postCreate(EntityStorageInterface $storage) {
        parent::postCreate($storage);
        // If it was not present in the $values passed to create(), (e.g. for
        // programmatic creation), populate the denormalized field_type property
        // from the field storage, so that it gets saved in the config record.
        if (empty($this->field_type)) {
            $this->field_type = $this->getFieldStorageDefinition()
                ->getType();
        }
        // Make sure all expected runtime settings are present.
        $default_settings = \Drupal::service('plugin.manager.field.field_type')->getDefaultFieldSettings($this->getType());
        // Filter out any unknown (unsupported) settings.
        $supported_settings = array_intersect_key($this->getSettings(), $default_settings);
        $this->set('settings', $supported_settings + $default_settings);
    }
    
    /**
     * {@inheritdoc}
     */
    public static function postDelete(EntityStorageInterface $storage, array $fields) {
        // Clear the cache upfront, to refresh the results of getBundles().
        \Drupal::service('entity_field.manager')->clearCachedFieldDefinitions();
        // Notify the entity storage.
        foreach ($fields as $field) {
            if (!$field->deleted) {
                \Drupal::service('field_definition.listener')->onFieldDefinitionDelete($field);
            }
        }
    }
    
    /**
     * {@inheritdoc}
     */
    public function postSave(EntityStorageInterface $storage, $update = TRUE) {
        // Clear the cache.
        \Drupal::service('entity_field.manager')->clearCachedFieldDefinitions();
        // Invalidate the render cache for all affected entities.
        $entity_type = $this->getFieldStorageDefinition()
            ->getTargetEntityTypeId();
        if ($this->entityTypeManager()
            ->hasHandler($entity_type, 'view_builder')) {
            $this->entityTypeManager()
                ->getViewBuilder($entity_type)
                ->resetCache();
        }
    }
    
    /**
     * {@inheritdoc}
     */
    public function getLabel() {
        return $this->label();
    }
    
    /**
     * {@inheritdoc}
     */
    public function setLabel($label) {
        $this->label = $label;
        return $this;
    }
    
    /**
     * {@inheritdoc}
     */
    public function getDescription() {
        return $this->description;
    }
    
    /**
     * {@inheritdoc}
     */
    public function setDescription($description) {
        $this->description = $description;
        return $this;
    }
    
    /**
     * {@inheritdoc}
     */
    public function isTranslatable() {
        // A field can be enabled for translation only if translation is supported.
        return $this->translatable && $this->getFieldStorageDefinition()
            ->isTranslatable();
    }
    
    /**
     * {@inheritdoc}
     */
    public function setTranslatable($translatable) {
        $this->translatable = $translatable;
        return $this;
    }
    
    /**
     * {@inheritdoc}
     */
    public function getSettings() {
        return $this->settings + $this->getFieldStorageDefinition()
            ->getSettings();
    }
    
    /**
     * {@inheritdoc}
     */
    public function setSettings(array $settings) {
        $this->settings = $settings + $this->settings;
        return $this;
    }
    
    /**
     * {@inheritdoc}
     */
    public function getSetting($setting_name) {
        if (array_key_exists($setting_name, $this->settings)) {
            return $this->settings[$setting_name];
        }
        else {
            return $this->getFieldStorageDefinition()
                ->getSetting($setting_name);
        }
    }
    
    /**
     * {@inheritdoc}
     */
    public function setSetting($setting_name, $value) {
        $this->settings[$setting_name] = $value;
        return $this;
    }
    
    /**
     * {@inheritdoc}
     */
    public function isRequired() {
        return $this->required;
    }
    
    /**
     * {@inheritdoc}
     */
    public function setRequired($required) {
        $this->required = $required;
        return $this;
    }
    
    /**
     * {@inheritdoc}
     */
    public function getDefaultValue(FieldableEntityInterface $entity) {
        // Allow custom default values function.
        if ($callback = $this->getDefaultValueCallback()) {
            $value = call_user_func($callback, $entity, $this);
            $value = $this->normalizeValue($value, $this->getFieldStorageDefinition()
                ->getMainPropertyName());
        }
        else {
            $value = $this->getDefaultValueLiteral();
        }
        // Allow the field type to process default values.
        $field_item_list_class = $this->getClass();
        return $field_item_list_class::processDefaultValue($value, $entity, $this);
    }
    
    /**
     * {@inheritdoc}
     */
    public function getDefaultValueLiteral() {
        return $this->default_value;
    }
    
    /**
     * {@inheritdoc}
     */
    public function setDefaultValue($value) {
        $this->default_value = $this->normalizeValue($value, $this->getFieldStorageDefinition()
            ->getMainPropertyName());
        return $this;
    }
    
    /**
     * {@inheritdoc}
     */
    public function getDefaultValueCallback() {
        return $this->default_value_callback;
    }
    
    /**
     * {@inheritdoc}
     */
    public function setDefaultValueCallback($callback) {
        $this->default_value_callback = $callback;
        return $this;
    }
    
    /**
     * Implements the magic __sleep() method.
     *
     * Using the Serialize interface and serialize() / unserialize() methods
     * breaks entity forms in PHP 5.4.
     * @todo Investigate in https://www.drupal.org/node/1977206.
     */
    public function __sleep() : array {
        $properties = get_object_vars($this);
        // Only serialize necessary properties, excluding those that can be
        // recalculated.
        unset($properties['itemDefinition'], $properties['original']);
        return array_keys($properties);
    }
    
    /**
     * {@inheritdoc}
     */
    public static function createFromItemType($item_type) {
        // Forward to the field definition class for creating new data definitions
        // via the typed manager.
        return BaseFieldDefinition::createFromItemType($item_type);
    }
    
    /**
     * {@inheritdoc}
     */
    public static function createFromDataType($type) {
        // Forward to the field definition class for creating new data definitions
        // via the typed manager.
        return BaseFieldDefinition::createFromDataType($type);
    }
    
    /**
     * {@inheritdoc}
     */
    public function getDataType() {
        // This object serves as data definition for field item lists, thus
        // the correct data type is 'list'. This is not to be confused with
        // the config schema type, 'field_config_base', which is used to
        // describe the schema of the configuration backing this objects.
        // @see \Drupal\Core\Field\FieldItemList
        // @see \Drupal\Core\TypedData\DataDefinitionInterface
        return 'list';
    }
    
    /**
     * {@inheritdoc}
     */
    public function isList() {
        return TRUE;
    }
    
    /**
     * {@inheritdoc}
     */
    public function getClass() {
        // Derive list class from the field type.
        $type_definition = \Drupal::service('plugin.manager.field.field_type')->getDefinition($this->getType());
        return $type_definition['list_class'];
    }
    
    /**
     * {@inheritdoc}
     */
    public function getConstraints() {
        return \Drupal::typedDataManager()->getDefaultConstraints($this) + $this->constraints;
    }
    
    /**
     * {@inheritdoc}
     */
    public function getConstraint($constraint_name) {
        $constraints = $this->getConstraints();
        return $constraints[$constraint_name] ?? NULL;
    }
    
    /**
     * {@inheritdoc}
     */
    public function getItemDefinition() {
        if (!isset($this->itemDefinition)) {
            $this->itemDefinition = FieldItemDataDefinition::create($this)->setSettings($this->getSettings());
            // Add any custom property constraints, overwriting as required.
            $item_constraints = $this->itemDefinition
                ->getConstraint('ComplexData') ?: [];
            foreach ($this->propertyConstraints as $name => $constraints) {
                if (isset($item_constraints[$name])) {
                    $item_constraints[$name] = $constraints + $item_constraints[$name];
                }
                else {
                    $item_constraints[$name] = $constraints;
                }
                $this->itemDefinition
                    ->addConstraint('ComplexData', $item_constraints);
            }
        }
        return $this->itemDefinition;
    }
    
    /**
     * {@inheritdoc}
     */
    public function getConfig($bundle) {
        return $this;
    }
    
    /**
     * {@inheritdoc}
     */
    public function setConstraints(array $constraints) {
        $this->constraints = $constraints;
        return $this;
    }
    
    /**
     * {@inheritdoc}
     */
    public function addConstraint($constraint_name, $options = NULL) {
        $this->constraints[$constraint_name] = $options;
        return $this;
    }
    
    /**
     * {@inheritdoc}
     */
    public function setPropertyConstraints($name, array $constraints) {
        $this->propertyConstraints[$name] = $constraints;
        // Reset the field item definition so the next time it is instantiated it
        // will receive the new constraints.
        $this->itemDefinition = NULL;
        return $this;
    }
    
    /**
     * {@inheritdoc}
     */
    public function addPropertyConstraints($name, array $constraints) {
        foreach ($constraints as $constraint_name => $options) {
            $this->propertyConstraints[$name][$constraint_name] = $options;
        }
        // Reset the field item definition so the next time it is instantiated it
        // will receive the new constraints.
        $this->itemDefinition = NULL;
        return $this;
    }
    
    /**
     * {@inheritdoc}
     */
    public function isInternal() {
        // Respect the definition, otherwise default to TRUE for computed fields.
        if (isset($this->definition['internal'])) {
            return $this->definition['internal'];
        }
        return $this->isComputed();
    }

}