Create an EntityCreatedInterface with accompanying trait to promote code reuse and standardization

Here is an initial implementation. I did not implement it for ContentTranslationMetadataWrapper since it is not an entity, even though it uses the same methods.

Forgot to add the trait to the User entity.

Is there any reason not to add 'created' to the existing entity_keys section?

I am not really sure. Entity keys are required and there must always be a present value.

Entity keys are documented in EntityTypeInterface::getKeys(). There are a couple of optional entity keys such as bundle and uuid but I don't think the created property is a good fit for the entity keys. The entity keys describe really basic properties from the entity object such as its ID, bundle and language. I feel like the created date is much too arbitrary to make sense as an entity key.

I personally think we shouldn't account for differences in the naming of the created property like is done in RevisionLogEntityTrait. I think this added complexity is overkill. I prefer the simple approach of providing a hardcoded key such as is done in EntityChangedTrait. These kind of traits are intended to provide consistency and improve the developer experience. If people really want to use a different machine name they can simply opt to not use the trait and implement their own getter and setter.

I'm wondering whether we could have a method for the base field as well. I know the EntityChangedTrait doesn't have it either but \Drupal\Core\Entity\RevisionLogEntityTrait does.

In RevisionLogEntityTrait this is possible because the base fields are added in the base class RevisionableContentEntityBase. We cannot do it in a similar way here because we can only have one base class. What we can do is provide a static method that returns the field definition, like in EntityPublishedTrait. This can then be easily included in baseFieldDefinitions():

public static function baseFieldDefinitions(EntityTypeInterface $entity_type) {
  $fields = parent::baseFieldDefinitions($entity_type);
  $fields += static::changedBaseFieldDefinitions($entity_type);
  return $fields;
}

I just found a trait where an undocumented entity key is used to make a similar property configurable: EntityPublishedTrait - it uses the undocumented 'published' entity key:

  public static function publishedBaseFieldDefinitions(EntityTypeInterface $entity_type) {
    if (!is_subclass_of($entity_type->getClass(), EntityPublishedInterface::class)) {
      throw new UnsupportedEntityTypeDefinitionException('The entity type ' . $entity_type->id() . ' does not implement \Drupal\Core\Entity\EntityPublishedInterface.');
    }
    if (!$entity_type->hasKey('published')) {
      throw new UnsupportedEntityTypeDefinitionException('The entity type ' . $entity_type->id() . ' does not have a "published" entity key.');
    }

    return [$entity_type->getKey('published') => BaseFieldDefinition::create('boolean')
      ->setLabel(new TranslatableMarkup('Publishing status'))
      ->setDescription(new TranslatableMarkup('A boolean indicating the published state.'))
      ->setRevisionable(TRUE)
      ->setTranslatable(TRUE)
      ->setDefaultValue(TRUE)];
  }

This changes my mind a bit about (ab)using entity keys for this purpose. If core is already doing it then we can follow this pattern.

I discussed this with @amateescu and @tstoeckler and the approach with the hardcoded key from EntityChangedTrait is considered as "the old way", and the approach with the abusing of undocumented entity keys from EntityPublishedTrait is "the new way". The uniqueness of the entity keys are not yet enforced in any way, but there is little danger for clashes. There is in fact already an issue to convert EntityChangedTrait to the new way: #2209971: Automatically provide a changed field definition.

I'll update the patch so it follows the example from EntityPublishedTrait.

Updated patch with the approach from EntityPublishedTrait and taking some inspiration from #2209971: Automatically provide a changed field definition.

Forgot to add the base field to the Node entity.

This is now hit with the same failures as are happening in #2209971: Automatically provide a changed field definition. The added entity key causes a schema change. Not sure how to proceed right now.

Nice, thanks! Let's do that :)

Postponing on #2841291: Fix NOT NULL handling in the entity storage and 'primary key' changes when updating the storage definition of an identifier field, it's RTBC so it might land pretty soon!