Commit | Line | Data |
---|---|---|
f9ec2da6 TO |
1 | <?php |
2 | namespace Civi\ActionSchedule\Event; | |
3 | ||
f9ec2da6 TO |
4 | use Symfony\Component\EventDispatcher\Event; |
5 | ||
6 | /** | |
7 | * Class MailingQueryEvent | |
8 | * @package Civi\ActionSchedule\Event | |
9 | * | |
10 | * This event allows listeners to modify the query which generates mailing data. | |
11 | * If you want to fetch extra mail-merge data as part of an initial query, then | |
12 | * modify the mailing-query to add extra JOINs/SELECTs. | |
13 | * | |
14 | * The basic mailing query looks a bit like this (depending on configuration): | |
15 | * | |
0b882a86 | 16 | * ``` |
f9ec2da6 TO |
17 | * SELECT reminder.id AS reminderID, reminder.contact_id as contactID, ... |
18 | * FROM `civicrm_action_log` reminder | |
19 | * ... JOIN `target_entity` e ON e.id = reminder.entity_id ... | |
20 | * WHERE reminder.action_schedule_id = #casActionScheduleId | |
0b882a86 | 21 | * ``` |
f9ec2da6 TO |
22 | * |
23 | * Listeners may modify the query. For example, suppose we want to load | |
24 | * additional fields from the related 'foo' entity: | |
25 | * | |
0b882a86 | 26 | * ``` |
f9ec2da6 TO |
27 | * $event->query->join('foo', '!casMailingJoinType civicrm_foo foo ON foo.myentity_id = e.id') |
28 | * ->select('foo.bar_value AS bar'); | |
0b882a86 | 29 | * ``` |
f9ec2da6 | 30 | * |
bc6ba616 TO |
31 | * Modifications may be used to do the following: |
32 | * | |
33 | * - Joining to business tables - to help target filter-criteria/temporal criteria on other entites. | |
34 | * (Ex: Join to the `civicrm_participant` table and filter on participant status or registration date.) | |
dbec742b TO |
35 | * - Joining business tables - to select/return additional columns. In particular, return the IDs of business-records that |
36 | * may be useful for token-handling. Use the prefix `tokenContext_*`. | |
37 | * Ex query: `$event->query->select('foo.id AS tokenContext_fooId') | |
38 | * Ex output: `$tokenRow->context['fooId']` | |
bc6ba616 | 39 | * |
f9ec2da6 TO |
40 | * There are several parameters pre-set for use in queries: |
41 | * - 'casActionScheduleId' | |
42 | * - 'casEntityJoinExpr' - eg 'e.id = reminder.entity_id' | |
43 | * - 'casMailingJoinType' - eg 'LEFT JOIN' or 'INNER JOIN' (depending on configuration) | |
44 | * - 'casMappingId' | |
45 | * - 'casMappingEntity' | |
46 | * | |
47 | * (Note: When adding more JOINs, it seems typical to use !casMailingJoinType, although | |
48 | * some hard-code a LEFT JOIN. Don't have an explanation for why.) | |
bc2feeb1 TO |
49 | * |
50 | * Event name: 'civi.actionSchedule.prepareMailingQuery' | |
f9ec2da6 TO |
51 | */ |
52 | class MailingQueryEvent extends Event { | |
53 | ||
54 | /** | |
55 | * The schedule record which produced this mailing. | |
56 | * | |
57 | * @var \CRM_Core_DAO_ActionSchedule | |
58 | */ | |
59 | public $actionSchedule; | |
60 | ||
61 | /** | |
62 | * The mapping record which produced this mailing. | |
63 | * | |
34f3bbd9 | 64 | * @var \Civi\ActionSchedule\MappingInterface |
f9ec2da6 TO |
65 | */ |
66 | public $mapping; | |
67 | ||
68 | /** | |
69 | * The alterable query. For details, see the class description. | |
70 | * @var \CRM_Utils_SQL_Select | |
71 | * @see MailingQueryEvent | |
72 | */ | |
73 | public $query; | |
74 | ||
75 | /** | |
76 | * @param \CRM_Core_DAO_ActionSchedule $actionSchedule | |
34f3bbd9 | 77 | * @param \Civi\ActionSchedule\MappingInterface $mapping |
f9ec2da6 TO |
78 | * @param \CRM_Utils_SQL_Select $query |
79 | */ | |
80 | public function __construct($actionSchedule, $mapping, $query) { | |
81 | $this->actionSchedule = $actionSchedule; | |
82 | $this->mapping = $mapping; | |
83 | $this->query = $query; | |
84 | } | |
85 | ||
86 | } |