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'sversion-historypath, with optionalfieldandoutputparameters. SeeDrupal\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. SeeDrupal\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.