New classes for auditing migration ID conflicts

When migrating content to a Drupal 8 site, it is posible that the Drupal 8 site already has content with the same ID that the source data is indicating. In this situation the existing content may be overwritten. To help prevent these kind of conflicts, ID auditing mechanism was added in #2876085: Before upgrading, audit for potential ID conflicts.

How to enable auditing for your migrations

If you want to enable auditing for a migration which uses the destination plugin EntityContentBase or the destination plugin is extending it, the only thing you need to do is to add audit: true to your migration's configuration as illustrated below.

id: d7_node
label: Nodes
audit: true
...
destination:
  plugin: entity:node

If you are not using or extending the EntityContentBasedestination plugin, your destination plugin needs to implement HighestIdInterface. More rarely, if you are not using or extending the Sql ID map plugin, your ID map plugin needs to implement HighestIdInterface.

New classes providing the auditing capabilities

interface AuditorInterface

Defines an interface for migration auditors. Classes that implement this interface must define two methods: audit() to audit one migration and auditMultiple() to audit a set of migrations.

class IdAuditor implements AuditorInterface

Audits migrations that create content entities in the destination system. It either returns an AuditResult or throws an AuditException.

class AuditResult

Encapsulates the result of a migration audit. It contains the audited migration, the result of the audit and the reasons why the migration passed or failed the audit.

class AuditException

Defines an exception to throw if an error occurs during a migration audit. An error occurs if the destination or the ID map plugins do not implement HighestIdInterface.

interface HighestIdInterface

Defines an interface for destination and ID maps which track a highest ID. Classes that implement this interface must define one method: getHighestId() which should return the highest ID tracked by the implementing plugin.

The EntityContentBase destination plugin and the Sql ID map plugin are now implementing the HighestIdInterface.