index.md

Unit tests

The headless unit tests are based on PHPUnit and cv. Simply run:

$ phpunit5

Events

!!! tip "Symfony Events"

This documentation references the [Symfony EventDispatcher](http://symfony.com/components/EventDispatcher).
If this is unfamiliar, you can read [a general introduction to Symfony events](http://symfony.com/doc/2.7/components/event_dispatcher.html)
or [a specific introduction about CiviCRM and Symfony events](https://docs.civicrm.org/dev/en/latest/hooks/setup/symfony/).

FlexMailer is an event based delivery system. It defines a few events:

• CheckSendableEvent: In this event, one examines a draft mailing to determine if it is complete enough to deliver.
• RunEvent: When a cron-worker starts processing a MailingJob, this event fires. It can be used to initialize resources... or to completely circumvent the normal process.
• WalkBatchesEvent: In this event, one examines the recipient list and pulls out a subset for whom you want to send email.
• ComposeBatchEvent: In this event, one examines the mail content and the list of recipients -- then composes a batch of fully-formed email messages.
• SendBatchEvent: In this event, one takes a batch of fully-formed email messages and delivers the messages.

These events are not conceived in the same way as a typical CiviCRM hook; rather, they resemble pipelines. For each event, several listeners have an opportunity to weigh-in, and the order of the listeners is important. As such, it helps to inspect the list of listeners. You can do this with the CLI command, cv:

$ cv debug:event-dispatcher /flexmail/
[Event] civi.flexmailer.checkSendable
+-------+------------------------------------------------------------+
| Order | Callable                                                   |
+-------+------------------------------------------------------------+
| #1    | Civi\FlexMailer\Listener\Abdicator->onCheckSendable()      |
| #2    | Civi\FlexMailer\Listener\RequiredFields->onCheckSendable() |
| #3    | Civi\FlexMailer\Listener\RequiredTokens->onCheckSendable() |
+-------+------------------------------------------------------------+

[Event] civi.flexmailer.walk
+-------+---------------------------------------------------+
| Order | Callable                                          |
+-------+---------------------------------------------------+
| #1    | Civi\FlexMailer\Listener\DefaultBatcher->onWalk() |
+-------+---------------------------------------------------+

[Event] civi.flexmailer.compose
+-------+-------------------------------------------------------+
| Order | Callable                                              |
+-------+-------------------------------------------------------+
| #1    | Civi\FlexMailer\Listener\BasicHeaders->onCompose()    |
| #2    | Civi\FlexMailer\Listener\ToHeader->onCompose()        |
| #3    | Civi\FlexMailer\Listener\BounceTracker->onCompose()   |
| #4    | Civi\FlexMailer\Listener\DefaultComposer->onCompose() |
| #5    | Civi\FlexMailer\Listener\Attachments->onCompose()     |
| #6    | Civi\FlexMailer\Listener\OpenTracker->onCompose()     |
| #7    | Civi\FlexMailer\Listener\HookAdapter->onCompose()     |
+-------+-------------------------------------------------------+

[Event] civi.flexmailer.send
+-------+--------------------------------------------------+
| Order | Callable                                         |
+-------+--------------------------------------------------+
| #1    | Civi\FlexMailer\Listener\DefaultSender->onSend() |
+-------+--------------------------------------------------+

The above listing shows the default set of listeners at time of writing. (Run the command yourself to see how they appear on your system.) The default listeners behave in basically the same way as CiviMail's traditional BAO-based delivery system (respecting mailerJobSize, mailThrottleTime, mailing_backend, hook_civicrm_alterMailParams, etal).

There are a few tricks for manipulating the pipeline:

• Register new listeners. Each event has its own documentation which describes how to do this.

• Manage the priority. When registering a listener, the addListener() function accepts a $priority integer. Use this to move up or down the pipeline.

  !!! note "Priority vs Order"

    When writing code, you will set the *priority* of a listener. The default is `0`, and the usual range is `2000` (first) to `-2000` (last).
  
    <!-- The default listeners have priorities based on the constants `FlexMailer::WEIGHT_PREPARE` (1000), `FlexMailer::WEIGHT_MAIN` (0),
    `FlexMailer::WEIGHT_ALTER` (-1000), and `FlexMailer::WEIGHT_END` (-2000). -->
  
    At runtime, the `EventDispatcher` will take all the listeners and sort them by priority. This produces the *order*, which simply counts up (`1`, `2`, `3`, ...).
  

• Alter a listener. Most listeners are services, and you can manipulate options on these services. For example, suppose you wanted to replace the default bounce-tracking mechanism. Here's a simple way to disable the default BounceTracker:

  <?php
  \Civi::service('civi_flexmailer_bounce_tracker')->setActive(FALSE);

  Of course, this change needs to be made before the listener runs. You might use a global hook (like hook_civicrm_config), or you might have your own listener which disables civi_flexmailer_bounce_tracker and adds its own bounce-tracking.

  Most FlexMailer services support setActive(), which enables you to completely replace them.

  Additionally, some services have their own richer methods. In this example, we modify the list of required tokens:

  <?php
  $tokens = \Civi::service('civi_flexmailer_required_tokens')
    ->getRequiredTokens();
  
  unset($tokens['domain.address']);
  
  \Civi::service('civi_flexmailer_required_tokens')
    ->setRequiredTokens($tokens);

Services

Most features in FlexMailer are implemented by services, and you can override or manipulate these features if you understand the corresponding service. For more detailed information about how to manipulate a service, consult its docblocks.

• Listener services (CheckSendableEvent)
  • civi_flexmailer_required_fields (RequiredFields.php): Check for fields like "Subject" and "From".
  • civi_flexmailer_required_tokens (RequiredTokens.php): Check for tokens like {action.unsubscribeUrl} (in traditional mailings).
• Listener services (WalkBatchesEvent)
  • civi_flexmailer_default_batcher (DefaultBatcher.php): Split the recipient list into smaller batches (per CiviMail settings)
• Listener services (ComposeBatchEvent)
  • civi_flexmailer_basic_headers (BasicHeaders.php): Add From:, Reply-To:, etc
  • civi_flexmailer_to_header (ToHeader.php): Add To: header
  • civi_flexmailer_bounce_tracker (BounceTracker.php): Add bounce-tracking codes
  • civi_flexmailer_default_composer (DefaultComposer.php): Read the email template and evaluate any tokens (based on CiviMail tokens)
  • civi_flexmailer_attachments (Attachments.php): Add attachments
  • civi_flexmailer_open_tracker (OpenTracker.php): Add open-tracking codes
  • civi_flexmailer_test_prefix (TestPrefix.php): Add a prefix to any test mailings
  • civi_flexmailer_hooks (HookAdapter.php): Backward compatibility with hook_civicrm_alterMailParams
• Listener services (SendBatchEvent)
  • civi_flexmailer_default_sender (DefaultSender.php): Send the batch using CiviCRM's default delivery service
• Other services
  • civi_flexmailer_html_click_tracker (HtmlClickTracker.php): Add click-tracking codes (for HTML messages)
  • civi_flexmailer_text_click_tracker (TextClickTracker.php): Add click-tracking codes (for plain-text messages)
  • civi_flexmailer_api_overrides (Services.php.php): Alter the Mailing APIs