Differences between branches 1.x and 2.x

The 2.x branch of this module is a complete rewrite to allow for some new features and bugfixes.

New features introduced in 2.x

• Support for revisions
  • A new record will be registered for each revision created.
• Support for translations
  • A new record will be registered for each translation, independently. (In 1.x only one usage was tracked, regardless of the number of translations using the target entity)
• Support for HTML links in WYSIWYG areas
• Support for config entities and content entities with string IDs
• Field name used to track is also available on usage page
• Configurable source / target entity types to be tracked
• Configurable active tracking plugins
• Support for tracking through basefields (also configurable)
• Batch update form exposed on the UI
• Improved usage list page
• A hook now allows modules to block usage tracking under arbitrary conditions
• Tracking plugins are now lighter and easier to implement
• Improved test coverage

Main BC-breaking changes from 1.x

Terminology changes

The main change in terminology is that the Host / Referencing / Source entity is now always referred to as Source, while the Destination / Target / Referenced entity is always referred to as Target.

API interface changes

The following methods were removed:

• \Drupal\entity_usage\EntityUsageInterface::add()
• \Drupal\entity_usage\EntityUsageInterface::delete()
• \Drupal\entity_usage\EntityUsageInterface::bulkDeleteHosts()
• \Drupal\entity_usage\EntityUsageInterface::listUsage()
• \Drupal\entity_usage\EntityUsageInterface::listReferencedEntities()

and replaced by these new methods:

• \Drupal\entity_usage\EntityUsageInterface::registerUsage()
• \Drupal\entity_usage\EntityUsageInterface::bulkDeleteSources()
• \Drupal\entity_usage\EntityUsageInterface::listSources()
• \Drupal\entity_usage\EntityUsageInterface::listTargets()

Also, new helper methods were created:

• \Drupal\entity_usage\EntityUsageInterface::deleteByField()
• \Drupal\entity_usage\EntityUsageInterface::deleteBySourceEntity()
• \Drupal\entity_usage\EntityUsageInterface::deleteByTargetEntity()

Please refer to the documentation on how to use the new methods. Also, a BC compatibility layer is provided for the methods ::listUsage() and ::listReferencedEntities(), read below for more information on this BC layer.

User-facing changes

The usage list page has changed to show information more relevant to the end user:

• The field name column was included
• The revision and language columns were included
• The tracking method column removed
• The count column was removed

Once each revision is tracked independently, on sites with lots of revisions this page can still end up with too much information and be hard to use. Work on improving this situation is being done on #2952210: Improve list usage page.

Data-storage changes

The schema has changed to make it possible to store the information needed for the new features. Apart from some renaming in favor of consistency, the columns:

• source_vid
• source_langcode
• field_name

were added to the DB table. Also, in order to support tracking entities with non-numeric IDs (such as config entities) without penalizing DB performance for numeric IDs, two additional columns

• target_id_string
• source_id_string

were created as well. This is handled transparently by the API though, so if you are not directly querying the database (and you shouldn't!), this won't affect you.

Tracking plugins architecture

This is probably the most disruptive change. The heavy work for the plugin behavior is now handled by the base class, and plugin implementations now only need to:

1. Extend  \Drupal\entity_usage\EntityUsageTrackBase
2. Define which field types they are able to track on their annotation
3. Implement the method  \Drupal\entity_usage\EntityUsageTrackInterface::getTargetEntities(), which should retrieve the target entity identifyer from a FieldItem value.

BC layer introduced for some helper methods

Sites calling the methods 

• \Drupal\entity_usage\EntityUsageInterface::listUsage()
• \Drupal\entity_usage\EntityUsageInterface::listReferencedEntities()

can keep using them because a BC layer is provided for those. The return value of these methods in 2.x has the same structure of those in 1.x. However, once now each revision / translation is tracked independently, the count returned is aggregated from all revisions / translations, so you will probably get a different count if a source has more than one revision / translation.