| 1 | <?php |
| 2 | /* |
| 3 | +--------------------------------------------------------------------+ |
| 4 | | Copyright CiviCRM LLC. All rights reserved. | |
| 5 | | | |
| 6 | | This work is published under the GNU AGPLv3 license with some | |
| 7 | | permitted exceptions and without any warranty. For full license | |
| 8 | | and copyright information, see https://civicrm.org/licensing | |
| 9 | +--------------------------------------------------------------------+ |
| 10 | */ |
| 11 | namespace Civi\FlexMailer; |
| 12 | |
| 13 | use Civi\FlexMailer\Event\ComposeBatchEvent; |
| 14 | use Civi\FlexMailer\Event\RunEvent; |
| 15 | use Civi\FlexMailer\Event\SendBatchEvent; |
| 16 | use Civi\FlexMailer\Event\WalkBatchesEvent; |
| 17 | use Symfony\Component\EventDispatcher\EventDispatcherInterface; |
| 18 | |
| 19 | /** |
| 20 | * Class FlexMailer |
| 21 | * @package Civi\FlexMailer |
| 22 | * |
| 23 | * The FlexMailer is a mail-blaster which supports batching and events. |
| 24 | * Specifically, there are five key events: |
| 25 | * - WalkBatchesEvent: Examine the recipient list and pull out a subset |
| 26 | * for whom you want to send email. |
| 27 | * - ComposeBatchEvent: Given a batch of recipients, prepare an email message |
| 28 | * for each. |
| 29 | * - SendBatchEvent: Given a batch of recipients and their messages, send |
| 30 | * the messages out. |
| 31 | * - RunEvent: Execute the main-loop (with all of the above steps). |
| 32 | * |
| 33 | * The events are based on Symfony's EventDispatcher. You may register event |
| 34 | * listeners using hook_civicrm_container, e.g. |
| 35 | * |
| 36 | * function mymod_civicrm_container(ContainerBuilder $container) { |
| 37 | * $container |
| 38 | * ->setDefinition('mymod_subscriber', new Definition('MymodSubscriber', array())) |
| 39 | * ->addTag('kernel.event_subscriber'); |
| 40 | * } |
| 41 | * |
| 42 | * FlexMailer includes default listeners for all of these events. They |
| 43 | * behaves in basically the same way as CiviMail's traditional BAO-based |
| 44 | * delivery system (respecting mailerJobSize, mailThrottleTime, |
| 45 | * mailing_backend, hook_civicrm_alterMailParams, etal). However, you |
| 46 | * can replace any of the major functions, e.g. |
| 47 | * |
| 48 | * - If you send large blasts across multiple servers, then you may |
| 49 | * prefer a different algorithm for splitting the recipient list. |
| 50 | * Listen for WalkBatchesEvent. |
| 51 | * - If you want to compose messages in a new way (e.g. a different |
| 52 | * templating language), then listen for ComposeBatchEvent. |
| 53 | * - If you want to deliver messages through a different medium |
| 54 | * (such as web-services or batched SMTP), listen for SendBatchEvent. |
| 55 | * |
| 56 | * In all cases, your function can listen to the event and then decide what |
| 57 | * to do. If your listener does the work required for the event, then |
| 58 | * you can disable the default listener by calling `$event->stopPropagation()`. |
| 59 | * |
| 60 | * @link http://symfony.com/doc/current/components/event_dispatcher.html |
| 61 | */ |
| 62 | class FlexMailer { |
| 63 | |
| 64 | const WEIGHT_START = 2000; |
| 65 | const WEIGHT_PREPARE = 1000; |
| 66 | const WEIGHT_MAIN = 0; |
| 67 | const WEIGHT_ALTER = -1000; |
| 68 | const WEIGHT_END = -2000; |
| 69 | |
| 70 | const EVENT_RUN = 'civi.flexmailer.run'; |
| 71 | const EVENT_WALK = 'civi.flexmailer.walk'; |
| 72 | const EVENT_COMPOSE = 'civi.flexmailer.compose'; |
| 73 | const EVENT_SEND = 'civi.flexmailer.send'; |
| 74 | |
| 75 | /** |
| 76 | * @return array |
| 77 | * Array(string $event => string $class). |
| 78 | */ |
| 79 | public static function getEventTypes() { |
| 80 | return array( |
| 81 | self::EVENT_RUN => 'Civi\\FlexMailer\\Event\\RunEvent', |
| 82 | self::EVENT_WALK => 'Civi\\FlexMailer\\Event\\WalkBatchesEvent', |
| 83 | self::EVENT_COMPOSE => 'Civi\\FlexMailer\\Event\\ComposeBatchEvent', |
| 84 | self::EVENT_SEND => 'Civi\\FlexMailer\\Event\\SendBatchEvent', |
| 85 | ); |
| 86 | } |
| 87 | |
| 88 | /** |
| 89 | * @var array |
| 90 | * An array which must define options: |
| 91 | * - mailing: \CRM_Mailing_BAO_Mailing |
| 92 | * - job: \CRM_Mailing_BAO_MailingJob |
| 93 | * - attachments: array |
| 94 | * - is_preview: bool |
| 95 | * |
| 96 | * Additional options may be passed. To avoid naming conflicts, use prefixing. |
| 97 | */ |
| 98 | public $context; |
| 99 | |
| 100 | /** |
| 101 | * @var \Symfony\Component\EventDispatcher\EventDispatcherInterface |
| 102 | */ |
| 103 | private $dispatcher; |
| 104 | |
| 105 | /** |
| 106 | * Create a new FlexMailer instance, using data available in the CiviMail runJobs(). |
| 107 | * |
| 108 | * @param \CRM_Mailing_BAO_MailingJob $job |
| 109 | * @param object $deprecatedMessageMailer |
| 110 | * @param array $deprecatedTestParams |
| 111 | * @return bool |
| 112 | * TRUE if delivery completed. |
| 113 | */ |
| 114 | public static function createAndRun($job, $deprecatedMessageMailer, $deprecatedTestParams) { |
| 115 | $flexMailer = new \Civi\FlexMailer\FlexMailer(array( |
| 116 | 'mailing' => \CRM_Mailing_BAO_Mailing::findById($job->mailing_id), |
| 117 | 'job' => $job, |
| 118 | 'attachments' => \CRM_Core_BAO_File::getEntityFile('civicrm_mailing', $job->mailing_id), |
| 119 | 'deprecatedMessageMailer' => $deprecatedMessageMailer, |
| 120 | 'deprecatedTestParams' => $deprecatedTestParams, |
| 121 | )); |
| 122 | return $flexMailer->run(); |
| 123 | } |
| 124 | |
| 125 | /** |
| 126 | * FlexMailer constructor. |
| 127 | * @param array $context |
| 128 | * An array which must define options: |
| 129 | * - mailing: \CRM_Mailing_BAO_Mailing |
| 130 | * - job: \CRM_Mailing_BAO_MailingJob |
| 131 | * - attachments: array |
| 132 | * @param \Symfony\Component\EventDispatcher\EventDispatcherInterface $dispatcher |
| 133 | */ |
| 134 | public function __construct($context = array(), EventDispatcherInterface $dispatcher = NULL) { |
| 135 | $this->context = $context; |
| 136 | $this->dispatcher = $dispatcher ? $dispatcher : \Civi::service('dispatcher'); |
| 137 | } |
| 138 | |
| 139 | /** |
| 140 | * @return bool |
| 141 | * TRUE if delivery completed. |
| 142 | * @throws \CRM_Core_Exception |
| 143 | */ |
| 144 | public function run() { |
| 145 | // PHP 5.3 |
| 146 | $flexMailer = $this; |
| 147 | |
| 148 | if (count($this->validate()) > 0) { |
| 149 | throw new \CRM_Core_Exception("FlexMailer cannot execute: invalid context"); |
| 150 | } |
| 151 | |
| 152 | $run = $this->fireRun(); |
| 153 | if ($run->isPropagationStopped()) { |
| 154 | return $run->getCompleted(); |
| 155 | } |
| 156 | |
| 157 | $walkBatches = $this->fireWalkBatches(function ($tasks) use ($flexMailer) { |
| 158 | $flexMailer->fireComposeBatch($tasks); |
| 159 | $sendBatch = $flexMailer->fireSendBatch($tasks); |
| 160 | return $sendBatch->getCompleted(); |
| 161 | }); |
| 162 | |
| 163 | return $walkBatches->getCompleted(); |
| 164 | } |
| 165 | |
| 166 | /** |
| 167 | * @return array |
| 168 | * List of error messages |
| 169 | */ |
| 170 | public function validate() { |
| 171 | $errors = array(); |
| 172 | if (empty($this->context['mailing'])) { |
| 173 | $errors['mailing'] = 'Missing \"mailing\"'; |
| 174 | } |
| 175 | if (empty($this->context['job'])) { |
| 176 | $errors['job'] = 'Missing \"job\"'; |
| 177 | } |
| 178 | return $errors; |
| 179 | } |
| 180 | |
| 181 | /** |
| 182 | * @return \Civi\FlexMailer\Event\RunEvent |
| 183 | */ |
| 184 | public function fireRun() { |
| 185 | $event = new RunEvent($this->context); |
| 186 | $this->dispatcher->dispatch(self::EVENT_RUN, $event); |
| 187 | return $event; |
| 188 | } |
| 189 | |
| 190 | /** |
| 191 | * @param callable $onVisitBatch |
| 192 | * @return \Civi\FlexMailer\Event\WalkBatchesEvent |
| 193 | */ |
| 194 | public function fireWalkBatches($onVisitBatch) { |
| 195 | $event = new WalkBatchesEvent($this->context, $onVisitBatch); |
| 196 | $this->dispatcher->dispatch(self::EVENT_WALK, $event); |
| 197 | return $event; |
| 198 | } |
| 199 | |
| 200 | /** |
| 201 | * @param array<FlexMailerTask> $tasks |
| 202 | * @return \Civi\FlexMailer\Event\ComposeBatchEvent |
| 203 | */ |
| 204 | public function fireComposeBatch($tasks) { |
| 205 | // This isn't a great place for this, but it ensures consistent cleanup. |
| 206 | $mailing = $this->context['mailing']; |
| 207 | if (property_exists($mailing, 'language') && $mailing->language && $mailing->language != 'en_US') { |
| 208 | $swapLang = \CRM_Utils_AutoClean::swap('call://i18n/getLocale', 'call://i18n/setLocale', $mailing->language); |
| 209 | } |
| 210 | |
| 211 | $event = new ComposeBatchEvent($this->context, $tasks); |
| 212 | $this->dispatcher->dispatch(self::EVENT_COMPOSE, $event); |
| 213 | return $event; |
| 214 | } |
| 215 | |
| 216 | /** |
| 217 | * @param array<FlexMailerTask> $tasks |
| 218 | * @return \Civi\FlexMailer\Event\SendBatchEvent |
| 219 | */ |
| 220 | public function fireSendBatch($tasks) { |
| 221 | $event = new SendBatchEvent($this->context, $tasks); |
| 222 | $this->dispatcher->dispatch(self::EVENT_SEND, $event); |
| 223 | return $event; |
| 224 | } |
| 225 | |
| 226 | } |