Commit f1464ad3 authored by MikeyMJCO's avatar MikeyMJCO
Browse files

Merge branch 'artfulrobot-merging' into 'master'

Improve hook_civicrm_merge docs

See merge request !957
parents 7b4d2770 7178c2b1
......@@ -6,6 +6,10 @@ This hook allows modification of the data used to perform merging of
duplicates. It can be useful if your custom module has added its own
tables related to CiviCRM contacts.
!!! note
If your extension has registered entities that have contact ID foreign keys defined correctly in their schema XML, these entities will be automatically handled by the merge process so you don’t need to implement this hook unless you need to do something fancy.
## Availability
This hook was first available in CiviCRM 3.2.3.
......@@ -51,37 +55,51 @@ passed:
merge operation. These SQL statements are run within a single transaction.
- `cidRefs`:
this is deprecated in favour of the entityTypes hook. If you alter cidRefs you will get a deprecation warning
an array of tables and their fields referencing
civicrm_contact.contact_id explicitly. Each table in the array has this format:
this is deprecated in favour of the entityTypes hook. If you alter cidRefs you will get a deprecation warning an array of tables and their fields referencing civicrm_contact.contact_id explicitly. Each table in the array has this format:
```php
'TABLE-NAME' => array('COLUMN-NAME' [, ...])
```
- `eidRefs`:
an array of tables and their fields referencing
`civicrm_contact.contact_id` with `entity_id`. Each table in the array has this format:
- `eidRefs`: an array of polymorphic tables and the names of the columns that hold the entity table name and ID to which they relate.
Each entry in the `$data` array has this format:
```php
'TABLE-NAME' => array('entity_table-COLUMN-NAME' => 'entity_id-COLUMN-NAME')
```
Example: `civicrm_note` uses two columns to identify the thing a note record relates to: `entity_table` and `entity_id`.
So if `civicrm_note` was not part of core and you wanted to include its contents in a merge, you might use this hook to set the following key and value in `$data` for the `eidRefs` invocation of this hook:
```php
'civicrm_note' => ['entity_table', 'entity_id']
```
## Example
```php
/** In this example we assume our module has created its own tables to store extra data on CiviCRM contacts:
* Table civitest_foo stores a relationship between two contacts, and contains the two relevant columns:
* civitest_foo.contact_id and civitest_foo.foo_id, both of which are foreign keys to civicrm_contact.id
* Table civitest_bar stores extra properties for contacts, and contains one relevant column:
* civitest_bar.contact_id is a foreign key to civicrm_contact.id
/**
* In this example we assume our module has created its own tables to
* store extra data on CiviCRM contacts:
*
* Table civitest_foo stores a relationship between two contacts, and
* contains the two relevant columns: civitest_foo.contact_id and
* civitest_foo.foo_id, both of which are foreign keys to civicrm_contact.id
*
* Table civitest_bar stores extra properties for contacts, and contains
* one relevant column: civitest_bar.contact_id is a foreign key to
* civicrm_contact.id
*
* This hook ensures that data in these two tables is included in CiviCRM merge operations.
* This hook ensures that data in these two tables is included in CiviCRM
* merge operations.
*/
function civitest_civicrm_merge($type, &$data, $mainId = NULL, $otherId = NULL, $tables = NULL) {
// If you are using Drupal and you use separate DBs for Drupal and CiviCRM, use the following to prefix
// your tables with the name of the Drupal database.
// If you are using Drupal and you use separate DBs for Drupal and
// CiviCRM, use the following to prefix your tables with the name of the
// Drupal database.
global $db_url;
if (!empty($db_url) {
$db_default = is_array($db_url) ? $db_url['default'] : $db_url;
......@@ -111,11 +129,12 @@ function civitest_civicrm_merge($type, &$data, $mainId = NULL, $otherId = NULL,
break;
case 'eidRefs':
// Add references to civitest_bar table, which is keyed to civicrm_contact.id
// using `bar_entity_id` column, when `entity_table` is equal to 'civicrm_contact'. By
// adding this to $data, records in this table will be automatically included in
// the merge.
$data[$db_default . 'civitest_bar'] = array('entity_table' => 'bar_entity_id');
// Add references to civitest_bar table, which is keyed to
// civicrm_contact.id using `bar_entity_id` column, when the value
// in its `entity_table` column is equal to 'civicrm_contact'. By
// adding this to $data, records in this table will be automatically
// included in the merge.
$data[$db_default . 'civitest_bar'] = ['entity_table' => 'bar_entity_id'];
break;
case 'sqls':
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment