Issue #2283977 by alexpott, Gábor Hojtsy, effulgentsia, fago: Create a new...

Issue #2283977 by alexpott, Gábor Hojtsy, effulgentsia, fago: Create a new ConfigEntity type for storing bundle-specific customizations of base fields.

core/config/schema/core.data_types.schema.yml

@@ -339,3 +339,45 @@ base_entity_reference_field_settings:
     target_bundle:
       type: string
       label: 'Bundle of item to reference'
+
+field_config_base:
+  type: config_entity
+  mapping:
+    id:
+      type: string
+      label: 'ID'
+    field_name:
+      type: string
+      label: 'Field name'
+    entity_type:
+      type: string
+      label: 'Entity type'
+    bundle:
+      type: string
+      label: 'Bundle'
+    label:
+      type: label
+      label: 'Label'
+    description:
+      type: text
+      label: 'Help text'
+    required:
+      type: boolean
+      label: 'Required field'
+    translatable:
+      type: boolean
+      label: 'Translatable'
+    default_value:
+      type: field.[%parent.field_type].value
+    default_value_function:
+      type: string
+      label: 'Default value function'
+    settings:
+      type: field.[%parent.field_type].instance_settings
+    field_type:
+      type: string
+      label: 'Field type'
+
+core.base_field_override.*.*.*:
+  type: field_config_base
+  label: 'Base field bundle override'

core/includes/entity.inc

@@ -67,6 +67,12 @@ function entity_invoke_bundle_hook($hook, $entity_type, $bundle, $bundle_new = N
   if (method_exists($storage, $method)) {
     $storage->$method($bundle, $bundle_new);
   }
+
+  // Notify the entity manager.
+  if (method_exists($entity_manager, $method)) {
+    $entity_manager->$method($entity_type, $bundle, $bundle_new);
+  }
+
   // Invoke hook_entity_bundle_*() hooks.
   \Drupal::moduleHandler()->invokeAll('entity_bundle_' . $hook, array($entity_type, $bundle, $bundle_new));
   // Clear the cached field definitions (not needed in case of 'create').

core/lib/Drupal/Core/Entity/ContentEntityBase.php

@@ -1033,7 +1033,7 @@ protected function getEntityKey($key) {
     if (!isset($this->entityKeys[$key]) || !array_key_exists($key, $this->entityKeys)) {
       if ($this->getEntityType()->hasKey($key)) {
         $field_name = $this->getEntityType()->getKey($key);
-        $property = $this->getFieldDefinition($field_name)->getMainPropertyName();
+        $property = $this->getFieldDefinition($field_name)->getFieldStorageDefinition()->getMainPropertyName();
         $this->entityKeys[$key] = $this->get($field_name)->$property;
       }
       else {

core/lib/Drupal/Core/Entity/ContentEntityInterface.php

@@ -44,17 +44,22 @@ public function initTranslation($langcode);
   /**
    * Provides base field definitions for an entity type.
    *
-   * Implementations typically use the class \Drupal\Core\Field\BaseFieldDefinition
-   * for creating the field definitions; for example a 'name' field could be
-   * defined as the following:
+   * Implementations typically use the class
+   * \Drupal\Core\Field\BaseFieldDefinition for creating the field definitions;
+   * for example a 'name' field could be defined as the following:
    * @code
    * $fields['name'] = BaseFieldDefinition::create('string')
    *   ->setLabel(t('Name'));
    * @endcode
    *
-   * If some elements in a field definition need to vary by bundle, use
+   * By definition, base fields are fields that exist for every bundle. To
+   * provide definitions for fields that should only exist on some bundles, use
    * \Drupal\Core\Entity\ContentEntityInterface::bundleFieldDefinitions().
    *
+   * The definitions returned by this function can be overridden for all
+   * bundles by hook_entity_base_field_info_alter() or overridden on a
+   * per-bundle basis via 'base_field_override' configuration entities.
+   *
    * @param \Drupal\Core\Entity\EntityTypeInterface $entity_type
    *   The entity type definition. Useful when a single class is used for multiple,
    *   possibly dynamic entity types.
@@ -69,14 +74,24 @@ public function initTranslation($langcode);
   public static function baseFieldDefinitions(EntityTypeInterface $entity_type);
 
   /**
-   * Provides or alters field definitions for a specific bundle.
-   *
-   * The field definitions returned here for the bundle take precedence on the
-   * base field definitions specified by baseFieldDefinitions() for the entity
-   * type.
-   *
-   * @todo Provide a better DX for field overrides.
-   *   See https://drupal.org/node/2145115.
+   * Provides field definitions for a specific bundle.
+   *
+   * This function can return definitions both for bundle fields (fields that
+   * are not defined in $base_field_definitions, and therefore might not exist
+   * on some bundles) as well as bundle-specific overrides of base fields
+   * (fields that are defined in $base_field_definitions, and therefore exist
+   * for all bundles). However, bundle-specific base field overrides can also
+   * be provided by 'base_field_override' configuration entities, and that is
+   * the recommended approach except in cases where an entity type needs to
+   * provide a bundle-specific base field override that is decoupled from
+   * configuration. Note that for most entity types, the bundles themselves are
+   * derived from configuration (e.g., 'node' bundles are managed via
+   * 'node_type' configuration entities), so decoupling bundle-specific base
+   * field overrides from configuration only makes sense for entity types that
+   * also decouple their bundles from configuration. In cases where both this
+   * function returns a bundle-specific override of a base field and a
+   * 'base_field_override' configuration entity exists, the latter takes
+   * precedence.
    *
    * @param \Drupal\Core\Entity\EntityTypeInterface $entity_type
    *   The entity type definition. Useful when a single class is used for multiple,

core/lib/Drupal/Core/Entity/EntityManager.php

@@ -471,8 +471,22 @@ protected function buildBundleFieldDefinitions($entity_type_id, $bundle, array $
     $entity_type = $this->getDefinition($entity_type_id);
     $class = $entity_type->getClass();
 
-    // Allow the entity class to override the base fields.
+    // Allow the entity class to provide bundle fields and bundle-specific
+    // overrides of base fields.
     $bundle_field_definitions = $class::bundleFieldDefinitions($entity_type, $bundle, $base_field_definitions);
+
+    // Load base field overrides from configuration. These take precedence over
+    // base field overrides returned above.
+    $base_field_override_ids = array_map(function($field_name) use ($entity_type_id, $bundle) {
+      return $entity_type_id . '.' . $bundle . '.' . $field_name;
+    }, array_keys($base_field_definitions));
+    $base_field_overrides = $this->getStorage('base_field_override')->loadMultiple($base_field_override_ids);
+    foreach ($base_field_overrides as $base_field_override) {
+      /** @var \Drupal\Core\Field\Entity\BaseFieldOverride $base_field_override */
+      $field_name = $base_field_override->getName();
+      $bundle_field_definitions[$field_name] = $base_field_override;
+    }
+
     $provider = $entity_type->getProvider();
     foreach ($bundle_field_definitions as $definition) {
       // @todo Remove this check once FieldDefinitionInterface exposes a proper
@@ -959,4 +973,28 @@ public function getEntityTypeFromClass($class_name) {
     throw new NoCorrespondingEntityClassException($class_name);
   }
 
+  /**
+   * Acts on entity bundle rename.
+   *
+   * @param string $entity_type_id
+   *   The entity type to which the bundle is bound.
+   * @param string $bundle_old
+   *   The previous name of the bundle.
+   * @param string $bundle_new
+   *   The new name of the bundle.
+   *
+   * @see entity_invoke_bundle_hook()
+   * @see entity_crud
+   */
+  public function onBundleRename($entity_type_id, $bundle_old, $bundle_new) {
+    // Rename existing base field bundle overrides.
+    $overrides = $this->getStorage('base_field_override')->loadByProperties(array('entity_type' => $entity_type_id, 'bundle' => $bundle_old));
+    foreach ($overrides as $override) {
+      $override->set('id', $entity_type_id . '.' . $bundle_new . '.' . $override->field_name);
+      $override->bundle = $bundle_new;
+      $override->allowBundleRename();
+      $override->save();
+    }
+  }
+
 }

core/lib/Drupal/Core/Field/BaseFieldDefinition.php

@@ -8,6 +8,7 @@
 namespace Drupal\Core\Field;
 
 use Drupal\Core\Entity\ContentEntityInterface;
+use Drupal\Core\Field\Entity\BaseFieldOverride;
 use Drupal\Core\Field\TypedData\FieldItemDataDefinition;
 use Drupal\Core\TypedData\ListDataDefinition;
 use Drupal\field\FieldException;
@@ -632,4 +633,15 @@ public function getUniqueStorageIdentifier() {
     return $this->getTargetEntityTypeId() . '-' . $this->getName();
   }
 
+  /**
+   * {@inheritdoc}
+   */
+  public function getConfig($bundle) {
+    $override = BaseFieldOverride::loadByName($this->getTargetEntityTypeId(), $bundle, $this->getName());
+    if ($override) {
+      return $override;
+    }
+    return BaseFieldOverride::createFromBaseFieldDefinition($this, $bundle);
+  }
+
 }

core/lib/Drupal/Core/Field/BaseFieldOverrideStorage.php

+<?php
+
+/**
+ * @file
+ * Contains \Drupal\Core\Field\BaseFieldOverrideStorage.
+ */
+
+namespace Drupal\Core\Field;
+
+use Drupal\Core\Entity\EntityTypeInterface;
+use Drupal\Core\Language\LanguageManagerInterface;
+use Symfony\Component\DependencyInjection\ContainerInterface;
+use Drupal\Core\Config\ConfigFactoryInterface;
+use Drupal\Component\Uuid\UuidInterface;
+
+/**
+ * Storage class for base field overrides.
+ */
+class BaseFieldOverrideStorage extends FieldConfigStorageBase {
+
+  /**
+   * Constructs a BaseFieldOverrideStorage object.
+   *
+   * @param \Drupal\Core\Entity\EntityTypeInterface $entity_type
+   *   The entity type definition.
+   * @param \Drupal\Core\Config\ConfigFactoryInterface $config_factory
+   *   The config factory service.
+   * @param \Drupal\Component\Uuid\UuidInterface $uuid_service
+   *   The UUID service.
+   * @param \Drupal\Core\Language\LanguageManagerInterface $language_manager
+   *   The language manager.
+   * @param \Drupal\Core\Field\FieldTypePluginManagerInterface $field_type_manager
+   *   The field type plugin manager.
+   */
+  public function __construct(EntityTypeInterface $entity_type, ConfigFactoryInterface $config_factory, UuidInterface $uuid_service, LanguageManagerInterface $language_manager, FieldTypePluginManagerInterface $field_type_manager) {
+    parent::__construct($entity_type, $config_factory, $uuid_service, $language_manager);
+    $this->fieldTypeManager = $field_type_manager;
+  }
+
+  /**
+   * {@inheritdoc}
+   */
+  public static function createInstance(ContainerInterface $container, EntityTypeInterface $entity_type) {
+    return new static(
+      $entity_type,
+      $container->get('config.factory'),
+      $container->get('uuid'),
+      $container->get('language_manager'),
+      $container->get('plugin.manager.field.field_type')
+    );
+  }
+
+}

core/lib/Drupal/Core/Field/Entity/BaseFieldOverride.php

+<?php
+
+/**
+ * @file
+ * Contains \Drupal\Core\Field\Entity\BaseFieldOverride.
+ */
+
+namespace Drupal\Core\Field\Entity;
+
+use Drupal\Component\Utility\String;
+use Drupal\Core\Entity\EntityStorageInterface;
+use Drupal\Core\Field\FieldConfigBase;
+use Drupal\Core\Field\BaseFieldDefinition;
+use Drupal\field\FieldException;
+
+/**
+ * Defines the base field override entity.
+ *
+ * Allows base fields to be overridden on the bundle level.
+ *
+ * @ConfigEntityType(
+ *   id = "base_field_override",
+ *   label = @Translation("Base field override"),
+ *   controllers = {
+ *     "storage" = "Drupal\Core\Field\BaseFieldOverrideStorage"
+ *   },
+ *   config_prefix = "base_field_override",
+ *   entity_keys = {
+ *     "id" = "id",
+ *     "label" = "label"
+ *   }
+ * )
+ */
+class BaseFieldOverride extends FieldConfigBase {
+
+  /**
+   * The base field definition.
+   *
+   * @var \Drupal\Core\Field\BaseFieldDefinition
+   */
+  protected $baseFieldDefinition;
+
+  /**
+   * Creates a base field override object.
+   *
+   * @param \Drupal\Core\Field\BaseFieldDefinition $base_field_definition
+   *   The base field definition to override.
+   * @param string $bundle
+   *   The bundle to which the override applies.
+   *
+   * @return \Drupal\Core\Field\Entity\BaseFieldOverride
+   *   A new base field override object.
+   */
+  public static function createFromBaseFieldDefinition(BaseFieldDefinition $base_field_definition, $bundle) {
+    $values = $base_field_definition->toArray();
+    $values['bundle'] = $bundle;
+    $values['baseFieldDefinition'] = $base_field_definition;
+    return \Drupal::entityManager()->getStorage('base_field_override')->create($values);
+  }
+
+  /**
+   * Constructs a BaseFieldOverride object.
+   *
+   * In most cases, base field override entities are created via
+   * BaseFieldOverride::createFromBaseFieldDefinition($definition, 'bundle')
+   *
+   * @param array $values
+   *   An array of base field bundle override properties, keyed by property
+   *   name. The field to override is specified by referring to an existing
+   *   field with:
+   *   - field_name: The field name.
+   *   - entity_type: The entity type.
+   *   Additionally, a 'bundle' property is required to indicate the entity
+   *   bundle to which the bundle field override is attached to. Other array
+   *   elements will be used to set the corresponding properties on the class;
+   *   see the class property documentation for details.
+   * @param string $entity_type
+   *   (optional) The type of the entity to create. Defaults to
+   *   'base_field_override'.
+   *
+   * @see entity_create()
+   *
+   * @throws \Drupal\field\FieldException
+   *   Exception thrown if $values does not contain a field_name, entity_type or
+   *   bundle value.
+   */
+  public function __construct(array $values, $entity_type = 'base_field_override') {
+    if (empty($values['field_name'])) {
+      throw new FieldException('Attempt to create a base field bundle override of a field without a field_name');
+    }
+    if (empty($values['entity_type'])) {
+      throw new FieldException(String::format('Attempt to create a base field bundle override of field @field_name without an entity_type', array('@field_name' => $values['field_name'])));
+    }
+    if (empty($values['bundle'])) {
+      throw new FieldException(String::format('Attempt to create a base field bundle override of field @field_name without a bundle', array('@field_name' => $values['field_name'])));
+    }
+
+    // Discard the 'field_type' entry that is added in config records to ease
+    // schema generation. See self::toArray().
+    unset($values['field_type']);
+
+    parent::__construct($values, $entity_type);
+  }
+
+  /**
+   * {@inheritdoc}
+   */
+  public function getFieldStorageDefinition() {
+    return $this->getBaseFieldDefinition()->getFieldStorageDefinition();
+  }
+
+  /**
+   * {@inheritdoc}
+   */
+  public function isDisplayConfigurable($context) {
+    return $this->getBaseFieldDefinition()->isDisplayConfigurable($context);
+  }
+
+  /**
+   * {@inheritdoc}
+   */
+  public function getDisplayOptions($display_context) {
+    return $this->getBaseFieldDefinition()->getDisplayOptions($display_context);
+  }
+
+  /**
+   * {@inheritdoc}
+   */
+  public function isReadOnly() {
+    return $this->getBaseFieldDefinition()->isReadOnly();
+  }
+
+  /**
+   * {@inheritdoc}
+   */
+  public function isComputed() {
+    return $this->getBaseFieldDefinition()->isComputed();
+  }
+
+  /**
+   * Gets the base field definition.
+   *
+   * @return \Drupal\Core\Field\BaseFieldDefinition
+   */
+  protected function getBaseFieldDefinition() {
+    if (!isset($this->baseFieldDefinition)) {
+      $fields = $this->entityManager()->getBaseFieldDefinitions($this->entity_type);
+      $this->baseFieldDefinition = $fields[$this->getName()];
+    }
+    return $this->baseFieldDefinition;
+  }
+
+  /**
+   * {@inheritdoc}
+   *
+   * @throws \Drupal\field\FieldException
+   *   If the bundle is being changed and
+   *   BaseFieldOverride::allowBundleRename() has not been called.
+   */
+  public function preSave(EntityStorageInterface $storage) {
+    // Set the default instance settings.
+    $this->settings += \Drupal::service('plugin.manager.field.field_type')->getDefaultInstanceSettings($this->getType());
+
+    // Call the parent's presave method to perform validate and calculate
+    // dependencies.
+    parent::preSave($storage);
+
+    if ($this->isNew()) {
+      // @todo This assumes that the previous definition isn't some
+      //   non-config-based override, but that might not be the case:
+      //   https://www.drupal.org/node/2321071.
+      $previous_definition = $this->getBaseFieldDefinition();
+    }
+    else {
+      // Some updates are always disallowed.
+      if ($this->entity_type != $this->original->entity_type) {
+        throw new FieldException(String::format('Cannot change the entity_type of an existing base field bundle override (entity type:@entity_type, bundle:@bundle, field name: @field_name)', array('@field_name' => $this->field_name, '@entity_type' => $this->entity_type, '@bundle' => $this->original->bundle)));
+      }
+      if ($this->bundle != $this->original->bundle && empty($this->bundleRenameAllowed)) {
+        throw new FieldException(String::format('Cannot change the bundle of an existing base field bundle override (entity type:@entity_type, bundle:@bundle, field name: @field_name)', array('@field_name' => $this->field_name, '@entity_type' => $this->entity_type, '@bundle' => $this->original->bundle)));
+      }
+      $previous_definition = $this->original;
+    }
+    // Notify the entity storage.
+    $this->entityManager()->getStorage($this->getTargetEntityTypeId())->onFieldDefinitionUpdate($this, $previous_definition);
+  }
+
+  /**
+   * {@inheritdoc}
+   */
+  public static function postDelete(EntityStorageInterface $storage, array $field_overrides) {
+    $entity_manager = \Drupal::entityManager();
+    // Clear the cache upfront, to refresh the results of getBundles().
+    $entity_manager->clearCachedFieldDefinitions();
+    /** @var \Drupal\Core\Field\Entity\BaseFieldOverride $field_override */
+    foreach ($field_overrides as $field_override) {
+      // Inform the system that the field definition is being updated back to
+      // its non-overridden state.
+      // @todo This assumes that there isn't a non-config-based override that
+      //   we're returning to, but that might not be the case:
+      //   https://www.drupal.org/node/2321071.
+      $entity_manager->getStorage($field_override->getTargetEntityTypeId())->onFieldDefinitionUpdate($field_override->getBaseFieldDefinition(), $field_override);
+    }
+  }
+
+  /**
+   * Loads a base field bundle override config entity.
+   *
+   * @param string $entity_type_id
+   *   ID of the entity type.
+   * @param string $bundle
+   *   Bundle name.
+   * @param string $field_name
+   *   Name of the field.
+   *
+   * @return static
+   *   The base field bundle override config entity if one exists for the
+   *   provided field name, otherwise NULL.
+   */
+  public static function loadByName($entity_type_id, $bundle, $field_name) {
+    return \Drupal::entityManager()->getStorage('base_field_override')->load($entity_type_id . '.' . $bundle . '.' . $field_name);
+  }
+
+  /**
+   * Implements the magic __sleep() method.
+   */
+  public function __sleep() {
+    // Only serialize necessary properties, excluding those that can be
+    // recalculated.
+    unset($this->baseFieldDefinition);
+    return parent::__sleep();
+  }
+
+}

core/lib/Drupal/Core/Field/FieldConfigBase.php

+<?php
+
+/**
+ * @file
+ * Contains \Drupal\Core\Field\FieldConfigBase.
+ */
+
+namespace Drupal\Core\Field;
+
+use Drupal\Core\Config\Entity\ConfigEntityBase;
+use Drupal\Core\Entity\ContentEntityInterface;
+use Drupal\Core\Entity\EntityStorageInterface;
+use Drupal\Core\Field\TypedData\FieldItemDataDefinition;
+
+/**
+ * Base class for configurable field definitions.
+ */
+abstract class FieldConfigBase extends ConfigEntityBase implements FieldConfigInterface {
+
+  /**
+   * The instance 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
+   */
+  public $id;
+
+  /**
+   * The name of the field attached to the bundle by this instance.
+   *
+   * @var string
+   */
+  public $field_name;
+
+  /**
+   * The name of the entity type the instance is attached to.
+   *
+   * @var string
+   */
+  public $entity_type;
+
+  /**
+   * The name of the bundle the instance is attached to.
+   *
+   * @var string
+   */
+  public $bundle;
+
+  /**
+   * The human-readable label for the instance.
+   *
+   * 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 field
+   * instances created in tests).
+   *
+   * @var string
+   */
+  public $label;
+
+  /**
+   * The instance 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 instance in entity edit forms.
+   *
+   * @var string
+   */
+  public $description = '';
+
+  /**
+   * Field-type specific settings.
+   *
+   * An array of key/value pairs. The keys and default values are defined by the
+   * field type.
+   *
+   * @var array
+   */
+  public $settings = array();
+
+  /**
+   * 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
+   */
+  public $required = FALSE;
+
+  /**
+   * Flag indicating whether the field is translatable.
+   *
+   * Defaults to TRUE.
+   *
+   * @var bool
+   */
+  public $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'