Remove deprecation from a hook that's actually uniquely useful

[highfalutin]

Overview

hook_civicrm_merge has a sub-hook cidRefs, documented here. This subhook has been deprecated since 2018 (@eileenmcnaughton) -- see the code change and the documentation change.

I'm glad the sub-hook was never removed after it was deprecated, because it actually offers something that hook_civicrm_entityTypes (the suggested replacement) does not: an opportunity to prevent an entity from being merged along with its associated Contact.

cidRefs is invoked only in the context of a merge, and there are some times when that's very helpful. I have a Flag entity that's joined to the Contact entity. In most contexts, I want the Flag's FK to civicrm_contact to behave as usual: the join should be accessible through API4 so that you can get the Contact for a Flag and the Flags for a Contact; a Flag should be cascade-deleted when its Contact is deleted. But, in my use case, Flags should not be reassigned when a Contact is merged into another Contact. The cidRefs sub-hook lets me do this by simply writing

function flagger_civicrm_merge($type, &$data, $idBeingKept = NULL, $idBeingDeleted = NULL, $tables = NULL) {
    if ('cidRefs' === $type) {
        unset($data['civicrm_flag']);
    }
}

entityTypes is a more blunt instrument. I can't accomplish what I want to do with entityTypes or with any hook besides cidRefs, to my knowledge.

Before

If you use the cidRefs phase of hook_civicrm_merge, you get a deprecation notice in your logs.

After

Nice control over the contact merge process, in peace and quiet.

[civibot]

(Standard links)

• If you are reviewing this pull-request, you may wish to consult the test sites and the Review Standards (long template, short template).

[aydun]

@eileenmcnaughton Any thoughts on this one? You've been doing a lot with merging.

[eileenmcnaughton]

@aydun @highfalutin I was kinda hoping to put in a new hook that would meet your needs - but I see I haven't gotten to it - so yes I will merge this now & not hold it hostage to my good intentions

[highfalutin]

Thank you!!! (and thanks for the nudge @aydun)