Civi/ActionSchedule/Event/MailingQueryEvent.php

   1 <?php
   2 namespace Civi\ActionSchedule\Event;
   3
   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  *
  16  * @code
  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
  21  * @endcode
  22  *
  23  * Listeners may modify the query. For example, suppose we want to load
  24  * additional fields from the related 'foo' entity:
  25  *
  26  * @code
  27  * $event->query->join('foo', '!casMailingJoinType civicrm_foo foo ON foo.myentity_id = e.id')
  28  *   ->select('foo.bar_value AS bar');
  29  * @endcode
  30  *
  31  * There are several parameters pre-set for use in queries:
  32  *  - 'casActionScheduleId'
  33  *  - 'casEntityJoinExpr' - eg 'e.id = reminder.entity_id'
  34  *  - 'casMailingJoinType' - eg 'LEFT JOIN' or 'INNER JOIN' (depending on configuration)
  35  *  - 'casMappingId'
  36  *  - 'casMappingEntity'
  37  *
  38  * (Note: When adding more JOINs, it seems typical to use !casMailingJoinType, although
  39  * some hard-code a LEFT JOIN. Don't have an explanation for why.)
  40  *
  41  * Event name: 'civi.actionSchedule.prepareMailingQuery'
  42  */
  43 class MailingQueryEvent extends Event {
  44
  45   /**
  46    * The schedule record which produced this mailing.
  47    *
  48    * @var \CRM_Core_DAO_ActionSchedule
  49    */
  50   public $actionSchedule;
  51
  52   /**
  53    * The mapping record which produced this mailing.
  54    *
  55    * @var \Civi\ActionSchedule\MappingInterface
  56    */
  57   public $mapping;
  58
  59   /**
  60    * The alterable query. For details, see the class description.
  61    * @var \CRM_Utils_SQL_Select
  62    * @see MailingQueryEvent
  63    */
  64   public $query;
  65
  66   /**
  67    * @param \CRM_Core_DAO_ActionSchedule $actionSchedule
  68    * @param \Civi\ActionSchedule\MappingInterface $mapping
  69    * @param \CRM_Utils_SQL_Select $query
  70    */
  71   public function __construct($actionSchedule, $mapping, $query) {
  72     $this->actionSchedule = $actionSchedule;
  73     $this->mapping = $mapping;
  74     $this->query = $query;
  75   }
  76
  77 }