Making an entity revisionable

Making an entity become revisionable is fairly simple, basically, you just need to define the entity's revision table and mark the fields to be revisionable.

This page provides an example of how to make an entity revisionable for Drupal 8, using the Content (ContentEntityBase) Entity Foo as an example.

1) Define the revision table

Entity types, both configuration and content entity are defined using annotation.
To define the revision table add revision_table information on your entity's annotation:

Example:

File: foo_module/src/Entity/Foo.php

*   revision_table = "foo_revision",

2) Define the Revision ID key

Revisions are referenced by the revision ID, so every revision of a single content has a revision ID.

Add the revision_id key on the entity's keys block:

Example:

File: <code>foo_module/src/Entity/Foo.php

...

 *   entity_keys = {
 *     "id" = "id",
 *     "revision" = "revision_id",
 *     "label" = "name",
 *     "uuid" = "uuid",
 *     "uid" = "user_id",
 *     "status" = "status",
 *   },

...

Note: The revision ID field will be automatically created by the parent class ContentEntityBase or RevisionableContentEntityBase if it is a content entity for example.

3) Make Entity Fields Revisionable

Before you make your entity fields revisionable, make sure that you are inheriting baseFieldDefinitions from the parent classes, ContentEntityBase or RevisionableContentEntityBase.

  /**
   * {@inheritdoc}
   */
  public static function baseFieldDefinitions(EntityTypeInterface $entity_type) {
    $fields = parent::baseFieldDefinitions($entity_type);

...

To make the fields of your Entity revisionable, use the method setRevisionable(TRUE).

Example:

File: foo_module/src/Entity/Foo.php

 /**
  * {@inheritdoc}
  */
 public static function baseFieldDefinitions(EntityTypeInterface $entity_type) {
  $fields = parent::baseFieldDefinitions($entity_type);

  $fields['created'] = BaseFieldDefinition::create('created')
    ->setLabel(t('Created'))
    ->setRevisionable(TRUE)
    ->setDescription(t('The time that the entity was created.'));

...

4) Update entity field definitions

For existing entity type, field definitions must be updated as described in Updating Entities and Fields in Drupal 8

5) Set new Revision on Entity save

To have a new revision created every time the entity is saved, you can use the method $entity->setNewRevision(); on save method of the Entity's form.

Example:

File: foo_module/src/Form/FooForm.php

 /**
  * {@inheritdoc}
  */
 public function save(array $form, FormStateInterface $form_state) {
   $entity = $this->entity;

   // Set new Revision.
   $entity->setNewRevision();

...

Final considerations

The implementation above is based on a basic Content Entity that is extending the base class ContentEntityBase. This class only set the revision_id field.

If you need to save additional information for your revisions, your entity should extend the class RevisionableContentEntityBase that brings the fields Revision created time, Revision user, Revision log messages. Or define the desired subset of fields yourself. Either way, in that case, make sure to also set the revision_metadata_keys entity type annotation.

As of Drupal 8.3 you can enable revision UI to add revision widget to entity form.