Skip to content

Extending

Field History defines no hooks, events or plugin types. Its service and route can be reused from custom code.

The field_history service

Drupal\field_history\FieldHistory works on any revisionable content entity.

Method Returns
getEntityTypes() The entity types that get Field History pages: revisionable content entity types with a version-history link template.
getFields(ContentEntityInterface $entity) The revisionable, non-computed fields of the entity, keyed by field name.
hasHistory(ContentEntityInterface $entity, string $field_name) Whether a field is one of those fields.
getChanges(ContentEntityInterface $entity) Revision IDs in which each field changed, oldest first, keyed by field name.
loadRevisions(ContentEntityInterface $entity, array $revision_ids) Those revisions of the entity, in the entity's language, keyed by revision ID.
getStoredValues(FieldItemListInterface $items) Each item's stored values, without runtime-only properties such as _loaded.
$field_history = \Drupal::service('field_history');
$changes = $field_history->getChanges($node);
// The revisions in which the title changed, oldest first.
$revisions = $field_history->loadRevisions($node, $changes['title']);
foreach ($revisions as $revision_id => $revision) {
  $title = $revision->label();
}

getChanges() checks no access. Check access to the entity and its fields before showing results, as FieldHistoryAccessCheck does for the module's pages.

Caching

getChanges() loads every revision of the entity once, 50 at a time, and stores the result in the cache.field_history bin, one entry per entity and language. The entry also holds the revision IDs it covers and the last value of each field. When revisions are added, only the new ones are loaded and compared with those values.

A full pass runs when a covered revision was deleted or the entity's fields changed. The module's entity hooks discard the entry when the entity, a revision or a translation is deleted, and when a revision is saved in place. Code that writes revision tables directly should call \Drupal::service('field_history')->invalidate($entity).

Entries are tagged field_history:{entity_type}:{id} and entity_field_info, not with the entity's own cache tags, which every save invalidates.

Routes, tabs and permissions

For each supported entity type, the module provides:

  • A route, entity.{entity_type}.field_history, beside the entity type's version-history path, with optional field and output parameters. See Drupal\field_history\Routing\FieldHistoryRoutes.
  • A Field History tab on the entity's canonical route. See Drupal\field_history\Plugin\Derivative\FieldHistoryLocalTasks.
  • A permission, view {entity_type} field history, which depends on the module that provides the entity type. See Drupal\field_history\FieldHistoryPermissions.
use Drupal\Core\Url;

$overview = Url::fromRoute('entity.node.field_history', ['node' => $nid]);
$timeline = Url::fromRoute('entity.taxonomy_term.field_history', [
  'taxonomy_term' => $tid,
  'field' => 'name',
]);

The routes' requirement _field_history_access: 'TRUE' applies Drupal\field_history\Access\FieldHistoryAccessCheck. It reads the entity type from the route's _field_history_entity_type default and combines the entity type's field history permission, the entity's view all revisions and view access and, when a field is given, field view access. A custom route can reuse it by setting both.