Last updated 11 October 2013. Created on 11 October 2013.
Edited by rlmumford. Log in to edit this page.

The main tool Entity Merge provides for Site Builders and Programmers is the entity_merge function. This page includes a rough guide to using the entity merge function.

entity_merge($entity1, $entity2, $entity_type [, $time = 0]);

Usually entity_merge takes 3 arguments; The two entities you wish to merge and the entity type of those entities. What actually happens in the merge is controlled by the entity type's "merge handler class". By default, all entities will use the EntityMergeHandlerDefault class but you can change this using hook_entity_info_alter().

The default merge handler registers a number of merge processes such as "merge_fields" and "invoke_hooks". These processes then get queued into a Drupal Queue. Usually this Queue is accessed and processed on cron.

Running a Merge Immediately

The fourth argument to entity_merge() allows you to specify a maximum running time in seconds. When this is set the entity_merge() function will run as much of the process as it can within the time specified. Anything that is not run within this time will remain in the queue and be processed on cron as usual.

Important: Setting this to a number that is higher than the PHP timeout limit can result in Fatal Errors.

Altering the Merge Process

Entity Merge provides two ways of interacting with merges; Hooks and registering additional merge processes.


The following hooks are invoked on every entity merge before the targetEntity has been saved to the database.

hook_entity_merge($targetEntity, $entity1, $entity2, $entity_type);
hook_entity_merge_ENTITY_TYPE($targetEntity, $entity1, $entity2);

They are invoked as part of the 'invoke_hooks' merge process.

Altering Merge Processes

It is possible to use the following hooks add and change the merge processes that will be run during an entity merge.

hook_entity_merge_register_processes($entity_type, $entity1, $entity2);
hook_entity_merge_register_processes_alter(&$processes, $entity_type, $context);

$processes is an array of process definitions keyed by a name unique within this merge. A process definition contains at least a 'class' that will run the process and a 'weight' for ordering. Process definitions can contain any other information the process requires, including the ability to pass different entities to the process using the 'entity1', 'entity2' and 'targetEntity' keys of the definition.

All process classes must extend EntityMergeProcessBase. (I'm working on an interface to remove this constraint, but this is still a work in progress).

Looking for support? Visit the forums, or join #drupal-support in IRC.