Entity Reference Revisions

Provides an Entity Reference field type that stores references to specific entity revisions, enabling composite entity relationships with revision tracking.

entity_reference_revisions

255,816 sites

128

drupal.org

field api gui

entity reference revisions composite entities paragraphs field type content modeling revision tracking orphan cleanup

Drupal 8 Drupal 9 Drupal 10 Drupal 11

Install

Drupal 11, 10 v8.x-1.13

composer require 'drupal/entity_reference_revisions:8.x-1.13'

Drupal 9 v8.x-1.12

composer require 'drupal/entity_reference_revisions:8.x-1.12'

Drupal 8 v8.x-1.9

composer require 'drupal/entity_reference_revisions:8.x-1.9'

Overview

The Entity Reference Revisions module extends Drupal's entity reference capability by adding revision support. Unlike the standard entity reference field that only stores the entity ID, this module stores both the entity ID and the specific revision ID, allowing you to maintain references to exact versions of entities.

This is particularly important for composite entities like Paragraphs, where child entities should create new revisions alongside their parent entities. The module handles automatic revision creation when the parent entity creates a new revision, ensuring data integrity and proper revision history.

The module also provides orphan cleanup functionality to automatically delete composite entity revisions that are no longer referenced by any parent entity, helping to keep the database clean and preventing orphaned data accumulation.

Features

Entity reference field type with revision tracking that stores both target_id and target_revision_id
Automatic revision creation for composite entities when parent creates new revision
Composite entity relationship support with parent type, parent ID, and parent field name tracking
Orphan composite entity cleanup via admin UI, Drush command, and cron queue worker
Views integration with custom display, style, and row plugins for entity reference selection
Migration destination plugin for importing entity revisions with proper ID mapping
Diff module integration for comparing entity reference revisions fields
Support for translatable and non-translatable composite entity references
Integration with core's options_select and options_buttons widgets
UUID-based default value support for configuration deployability

Use Cases

Building modular content with Paragraphs

The most common use case is with the Paragraphs module. When creating structured content with multiple paragraph types (text, images, galleries, etc.), Entity Reference Revisions ensures that when you create a new revision of a node, all referenced paragraphs also get new revisions. This maintains complete revision history and allows reverting to previous content states including all nested paragraph content.

Implementing content components that belong to their parent

Use Entity Reference Revisions when you need child entities that are 'owned' by a parent entity and should be deleted when the parent is deleted. Unlike standard entity references where the referenced entity is independent, composite entities created via ERR fields are meant to exist only as part of their parent.

Maintaining audit trails for complex content structures

When content compliance requires tracking changes to all content components, ERR ensures revision history is maintained throughout the content hierarchy. Each change to a nested component creates a new revision that can be tracked, compared, and reverted.

Cleaning up orphaned content components

Use the admin UI or Drush command to periodically clean up composite entities that are no longer referenced. This can happen when content is deleted outside normal workflows or when database maintenance is needed.

Migrating content with revision preservation

When migrating content from another system that includes revision history, use the entity_reference_revisions migration destination to import entities while preserving their revision structure and parent-child relationships.

Tips

Use Entity Reference Revisions for any entity type that should be treated as a composite/embedded entity that belongs to its parent, not just for Paragraphs
Run the orphan cleanup periodically via cron or Drush, especially after bulk content operations or migrations
When implementing custom composite entity types, include entity_revision_parent_type_field, entity_revision_parent_id_field, and entity_revision_parent_field_name_field in your entity type definition
For migration, set new_revisions: true in destination configuration to preserve existing content while adding migrated revisions
The options_select and options_buttons widgets from core work with Entity Reference Revisions fields - useful for limited selection sets
Monitor the entity_reference_revisions_orphan_purger queue during cron if you experience performance issues with large amounts of composite content

Dependencies

Field Required

Related Projects

views Core

Provides custom display, style, and row plugins for Views-based entity reference selection. Adds field relationship data via hook_field_views_data() for both forward and reverse entity relationships based on revision IDs.

diff

Provides a FieldDiffBuilder plugin that enables comparison of entity reference revisions fields. Parses the referenced entities to extract field values for detailed diff output.

migrate Core

Provides a destination plugin for migrating entities with revision tracking. Supports creating new revisions, forced revision creation, translation rollback, and proper ID mapping for both entity ID and revision ID.

paragraphs

Primary use case module. Paragraphs implements EntityNeedsSaveInterface and uses entity_revision_parent_* fields to establish composite relationships. Entity Reference Revisions handles automatic revision synchronization and orphan cleanup for paragraph entities.

Technical Details

Delete orphaned composite entities /admin/config/system/delete-orphans

This administrative page allows you to delete orphaned composite entity revisions that are no longer referenced by any parent entity. Orphaned entities can occur when parent entities are deleted or when entity reference fields are changed. Running this cleanup helps maintain database integrity and prevents storage bloat.

Delete orphan revisions

Allows access to the Entity Reference Revisions orphan deletion form at /admin/config/system/delete-orphans. Users with this permission can trigger the cleanup of orphaned composite entity revisions.

hook_entity_revision_create

Creates new revisions of composite entities when the parent entity creates a new revision. Ensures that non-translatable entity reference revisions fields properly propagate revision creation to their referenced entities.

hook_field_widget_info_alter

Adds the entity_reference_revisions field type to the options_select and options_buttons widgets, allowing these standard widgets to be used for entity reference revisions fields.

hook_field_storage_config_update

Resets the handler settings when the target type of an entity reference revisions field is changed, ensuring field configuration remains valid.

hook_entity_delete

Queues orphan cleanup for composite entities when a parent entity is deleted. Finds all composite entity revisions that reference the deleted entity and queues them for the orphan purger.

drush err:purge

Deletes orphaned composite entity revisions that are no longer referenced by any parent entity. Runs as a batch process with progress reporting.

The 'delete orphan revisions' permission should be granted carefully as the cleanup process permanently deletes data
Always backup your database before running bulk orphan cleanup operations
The orphan cleanup admin form displays a warning about potential data loss if the cleanup incorrectly identifies used entities