ext/flexmailer/docs/develop/RunEvent.md

   1 The `RunEvent` (`EVENT_RUN`) fires as soon as FlexMailer begins processing a job.
   2
   3 CiviMail has a recurring task -- `Job.process_mailings` -- which identifies scheduled/pending mailings.  It determines
   4 the `Mailing` and `MailingJob` records, then passes control to `FlexMailer` to perform delivery.  `FlexMailer`
   5 immediately fires the `RunEvent`.
   6
   7 !!! note "`RunEvent` fires for each cron-run."
   8
   9     By default, FlexMailer uses `DefaultBatcher` which obeys the traditional CiviMail throttling behavior.  This can
  10     limit the number of deliveries performed within a single cron-run.  If you reach this limit, then it stops
  11     execution.  However, after 5 or 10 minutes, a new *cron-run* begins.  It passes control to FlexMailer again, and
  12     then we pick up where we left off.  This means that one `Mailing` and one `MailingJob` could require multiple
  13     *cron-runs*.
  14
  15     The `RunEvent` would fire for *every cron run*.
  16
  17 To listen to the `RunEvent`:
  18
  19 ```php
  20 <?php
  21 function example_civicrm_container($container) {
  22   $container->addResource(new \Symfony\Component\Config\Resource\FileResource(__FILE__));
  23   $container->findDefinition('dispatcher')->addMethodCall('addListener',
  24     array(\Civi\FlexMailer\FlexMailer::EVENT_RUN, '_example_run')
  25   );
  26 }
  27
  28 function _example_run(\Civi\FlexMailer\Event\RunEvent $event) {
  29   printf("Starting work on job #%d for mailing #%d\n", $event->getJob()->id, $event->getMailing()->id);
  30 }
  31 ```
  32
  33 !!! note "Stopping the `RunEvent` will stop FlexMailer."
  34
  35     If you call `$event->stopPropagation()`, this will cause FlexMailer to
  36     stop its delivery process.