From ffe1997da404bc7ec56a9062e6bc1dc2aec93762 Mon Sep 17 00:00:00 2001
From: "deb.monish" <deb.monish@gmail.com>
Date: Sun, 16 Jul 2017 18:18:09 +0530
Subject: [PATCH] CRM-20845: document alterMailingRecipients hook
---
.../hook_civicrm_alterMailingRecipients.md | 49 +++++++++++++++++++
docs/hooks/list.md | 1 +
2 files changed, 50 insertions(+)
create mode 100644 docs/hooks/hook_civicrm_alterMailingRecipients.md
diff --git a/docs/hooks/hook_civicrm_alterMailingRecipients.md b/docs/hooks/hook_civicrm_alterMailingRecipients.md
new file mode 100644
index 00000000..36c31eaa
--- /dev/null
+++ b/docs/hooks/hook_civicrm_alterMailingRecipients.md
@@ -0,0 +1,49 @@
+# hook_civicrm_alterMailingRecipients
+
+## Summary
+
+This hook is called to allow the user to alter the mailing recipients after they have been constructed.
+
+### Notes
+
+!!! Note
+ This hook is called two times, once at the start and once at the end of mail recipients
+ building, identified by $context as 'pre' or 'post' respectively
+
+## Availability
+
+This hook was first available in CiviCRM 4.7.32
+
+## Definition
+
+```php
+ function hook_civicrm_alterMailingRecipients(&$mailingObject, &$criteria, $context);
+```
+
+## Parameters
+
+- object `$mailingObject` - reference to CRM_Mailing_DAO_Mailing object
+- array `$criteria` - the criteria in terms of SQL fragments Array(string $name => CRM_Utils_SQL_Select $criterion) to manipulate mailing recipients
+- string `$context` - contain 'pre' or 'post' value to indicate when the hook is fired
+
+## Returns
+
+- null
+
+## Example
+```php
+ function mymodule_civicrm_alterMailingRecipients(&$mailingObject, &$criteria, $context) {
+ // fetch all emails marked is_bulkmail only AND consider only those contacts which are tagged with Volunteer
+ if ($context == 'pre') {
+ // criteria to choose email which are only used for mass mailing
+ $criteria['location_filter'] = CRM_Utils_SQL_Select::fragment()->where("civicrm_email.is_bulkmail = 1");
+ // criteria to choose contacts which are tagged 'Volunteer'
+ $criteria['tag_filter'] = CRM_Utils_SQL_Select::fragment()
+ ->join('civicrm_entity_tag', "INNER JOIN civicrm_entity_tag et ON et.entity_id = civicrm_contact.id AND et.entity_table = 'civicrm_contact'")
+ ->join('civicrm_tag', "INNER JOIN civicrm_tag t ON t.id = et.tag_id")
+ ->where("t.name = 'Volunteer'");
+ // criteria to change order by to use is_bulkmail
+ $criteria['order_by'] = CRM_Utils_SQL_Select::fragment()->orderBy('civicrm_email.is_bulkmail')
+ }
+ }
+```
diff --git a/docs/hooks/list.md b/docs/hooks/list.md
index 2ae2e1f6..d9aa20f8 100644
--- a/docs/hooks/list.md
+++ b/docs/hooks/list.md
@@ -86,6 +86,7 @@ This is an overview list of all available hooks, listed by category.
* **[hook_civicrm_alterMailContent](/hooks/hook_civicrm_alterMailContent.md)** - called after getting the content of the mail and before tokenizing it.
* **[hook_civicrm_alterMailer](/hooks/hook_civicrm_alterMailer.md)** - called when CiviCRM prepares an email driver class to handle outbound message delivery.
* **[hook_civicrm_alterMailParams](/hooks/hook_civicrm_alterMailParams.md)** - called when an email is about to be sent by CiviCRM.
+* **[hook_civicrm_alterMailingRecipients](/hooks/hook_civicrm_alterMailingRecipients.md)** - called twice, once before and once after constructing mail recipients.
* **[hook_civicrm_emailProcessor](/hooks/hook_civicrm_emailProcessor.md)** - called after *each* email has been processed by the script `bin/EmailProcessor.php`.
* **[hook_civicrm_emailProcessorContact](/hooks/hook_civicrm_emailProcessorContact.md)** - called by the Email Processor when deciding to which contact and activity will be attached.
* **[hook_civicrm_mailingGroups](/hooks/hook_civicrm_mailingGroups.md)** - called when composing a mailing allowing you to include or exclude other groups as needed.
--
GitLab