Entity Reference vs Entity Reference Revisions: A Developer’s Guide

When building content relationships in Drupal, entity references are the go-to solution. Drupal provides a core Entity Reference field, and the contributed module Entity Reference Revisions(ERR) extends this functionality. Understanding the differences and appropriate use cases for each is essential for designing flexible and reliable content architectures.

Scenario: Properties and Rooms

Imagine we are having properties and rooms in our real estate Drupal website, where rooms are not standalone content items; they are part of a property and should only be created or edited within the Property form with the help of the Inline Entity Form module. 

For the sake of this article, we need to download and install the Inline Entity Form module and also create two content types:

• Property content type with no extra fields so far. 

• Room content type with an extra boolean field called bookable.

Now, let’s build the relationship between them using two different field types to understand and visualize the difference:

Entity Reference: Core Field for Linking Content

The Entity Reference field is part of Drupal core and allows linking one entity to another such as referencing a taxonomy term or a user.

Let’s continue working on our example and add an entity reference field called “Rooms” to the Property content type, which references the Rooms contents.

Image

From the Manage form display, set the Inline entity form widget for the rooms field so that we can create/edit rooms inside the property form.

Image

Let’s go ahead and create a property node and make sure you also fill in the Room’s fields.

Image

We just created a property node with a Bedroom line item and set the bedroom’s bookable field value to “Yes”.

Now let’s edit the same property node and change its title as well as the Bedroom title, and also change the bookable field value to “NO” while making sure the Create new revision option is enabled in the edit form.

Image

Nothing new so far. Right? Yeah, the Property node has been updated. But if we go to the revisions page of the same node, we see that there are two revisions created at this moment.

Image

The current revision is the latest updated version of the content node. What happens if we revert to the last revision of the node? Let’s try and see:

Image

The property title has changed back to the previous version, but the room title remains the same as last updated, as well as the bookable field still showing “NO,” which means the Room’s referenced content did not revert to the previous version when we reverted the parent content, which is the property in our case.

What happened here is the limitation of the core Entity Reference field, which only store the referenced entity ID, meaning the referenced entity is always loaded in its latest revision. This is fine for stable, global content like taxonomy terms or user profiles, but it creates challenges when referencing versioned or embedded content.

Solution: Entity Reference Revisions

The Entity Reference Revisions (ERR) field type is provided by the Entity Reference Revisions module. It is very similar to the Entity Reference field in core, but it stores a reference to a specific revision of an entity, in addition to its ID, which offers more flexibility when it comes to reverting to a previous revision in the case when you have a nested entity.

Now, let’s rebuild the relationship between Property and Rooms with the help of this new field type, but before that, we need to download and enable the Entity Reference Revisions module.

On the Property content type, let’s remove the previously added Rooms field and add it back. Again, we need to select “Reference” on the Add field form, like in the screenshot below:

Image

On the next screen, this time we select “Other (revisions)” :

Image

This way we just added a field of type Entity reference revisions. From the Manage form display, again we want to set the Inline entity form - Simple widget for this new field, and also under the widget setting, it’s important to enable the checkbox for Create new revision.

Now let’s test again by creating a new Property node and filling the form fields with the same values.

Image

Repeating the same steps to test, let’s now edit and update the values of the Property node.

Image

Again, nothing special so far. We updated the field values of the Property and Rooms. But the pleasing part is that if we go to the revisions page and revert to the previous revision of the Property node. After reverting, we see the content is now fully reverted to the previous version. Yes! both the Property field itself as well as the fields of the Room line item.

Image

This is what we wanted to see. It looks really nice. Isn’t it? How it works is that the ERR field type allows you to reference a specific entity revision by storing the revision ID of the referenced content in addition to the content ID. This is particularly useful when you want to embed structured content inside a parent entity and want their content versioned with the parent.

Developer Perspective

Here is how we programmatically define fields of both type Entity Reference and ERR:

Entity Reference:

$fields['field_room'] = BaseFieldDefinition::create('entity_reference')
  ->setLabel(t('Room'))
  ->setSetting('target_type', 'node')
  ->setSetting('handler', 'default')
  ->setSetting('handler_settings', ['target_bundles' => [room => room]])
  ->setDisplayConfigurable('form', TRUE)
  ->setDisplayConfigurable('view', TRUE);

Entity Reference Revisions:

$fields['field_room'] = BaseFieldDefinition::create('entity_reference_revisions')
  ->setLabel(t('Room'))
  ->setSetting('target_type', 'node')
  ->setSetting('handler', 'default')
  ->setSetting('handler_settings', ['target_bundles' => [room => room]])
  ->setDisplayConfigurable('form', TRUE)
  ->setDisplayConfigurable('view', TRUE);

Programmatically setting the value of the ERR field is different, too. See example below:

// Considering field_rooms is a multi-valued ERR field.
$property->set('field_rooms', [
 [
  'target_id' => $room->id(),
  'target_revision_id' => $room->getRevisionId(),
 ]
]);

Summary

To summarise, an Entity Reference is useful when the referenced content stands on its own. Entity Reference Revisions (ERR) are like embedding parts of your content that live and die with the parent.

To close the discussion on this topic, I want to add a final note that the popular Paragraphs module is out of the box using the ERR field type. Also, the usability of the ERR module can really become enjoyable with the use of the Diff module, which allows pretty viewing of all added/changed/deleted words between revisions.