By amateescu on
Change record status: 
Published (View all published change records)
Project: 
Drupal core
Introduced in branch: 
8.4.x
Introduced in version: 
8.4.0-beta1
Issue links: 
https://www.drupal.org/node/2346019
Description: 

When installing a new base field to a content entity type, an initial value can be specified and all the existing entities will automatically have the specified value for that field. This value may or may not match the default value, in fact required fields may not have a default value at all.

For this feature, two methods have been added to \Drupal\Core\Field\BaseFieldDefinition: setInitialValue() and setInitialValueFromField().

Note that adding a base field with an initial value usually makes sense only update functions, when we are adding a field to an entity type that already contains data, so the setInitialValue() and setInitialValueFromField() methods should only be used in that specific update function and not copied to the base field definition from the entity class (i.e. in EntityTypeClass::baseFieldDefinitions()).

Usage examples:

setInitialValue() can be used to set a fixed initial value:

$storage_definition = BaseFieldDefinition::create('string')
  ->setLabel(new TranslatableMarkup('A new base field'))
  ->setInitialValue('test value');

When the field type has multiple properties, the initial value can be specified as an array:

$storage_definition = BaseFieldDefinition::create('text')
  ->setLabel(new TranslatableMarkup('A new base field with multiple properties'))
  ->setInitialValue(['value' => 'test value', 'format' => 'plain_text']);

setInitialValueFromField() can be used to copy the initial value from another base field, for example:

$storage_definition = BaseFieldDefinition::create('string')
  ->setLabel(new TranslatableMarkup('A new base field'))
  ->setInitialValueFromField('title');

Note that the "from" field can only be another base field (i.e. stored in the shared tables) and the field types have to be the same!

Impacts: 
Module developers