Plugins

AntiFlood Plugin

Many SMTP servers have limits on the number of messages that may be sent during any single SMTP connection. The AntiFlood plugin provides a way to stay within this limit while still managing a large number of emails.

A typical limit for a single connection is 100 emails. If the server you connect to imposes such a limit, it expects you to disconnect after that number of emails has been sent. You could manage this manually within a loop, but the AntiFlood plugin provides the necessary wrapper code so that you don't need to worry about this logic.

Regardless of limits imposed by the server, it's usually a good idea to be conservative with the resources of the SMTP server. Sending will become sluggish if the server is being over-used so using the AntiFlood plugin will not be a bad idea even if no limits exist.

The AntiFlood plugin's logic is basically to disconnect and the immediately re-connect with the SMTP server every X number of emails sent, where X is a number you specify to the plugin.

You can also specify a time period in seconds that Swift Mailer should pause for between the disconnect/re-connect process. It's a good idea to pause for a short time (say 30 seconds every 100 emails) simply to give the SMTP server a chance to process its queue and recover some resources.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

// Create the Mailer using any Transport
$mailer = new Swift_Mailer(
  new Swift_SmtpTransport('smtp.example.org', 25)
);

// Use AntiFlood to re-connect after 100 emails
$mailer->registerPlugin(new Swift_Plugins_AntiFloodPlugin(100));

// And specify a time in seconds to pause for (30 secs)
$mailer->registerPlugin(new Swift_Plugins_AntiFloodPlugin(100, 30));

// Continue sending as normal
for ($lotsOfRecipients as $recipient) {
  ...

  $mailer->send( ... );
}

Throttler Plugin

If your SMTP server has restrictions in place to limit the rate at which you send emails, then your code will need to be aware of this rate-limiting. The Throttler plugin makes Swift Mailer run at a rate-limited speed.

Many shared hosts don't open their SMTP servers as a free-for-all. Usually they have policies in place (probably to discourage spammers) that only allow you to send a fixed number of emails per-hour/day.

The Throttler plugin supports two modes of rate-limiting and with each, you will need to do that math to figure out the values you want. The plugin can limit based on the number of emails per minute, or the number of bytes-transferred per-minute.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

// Create the Mailer using any Transport
$mailer = new Swift_Mailer(
  new Swift_SmtpTransport('smtp.example.org', 25)
);

// Rate limit to 100 emails per-minute
$mailer->registerPlugin(new Swift_Plugins_ThrottlerPlugin(
  100, Swift_Plugins_ThrottlerPlugin::MESSAGES_PER_MINUTE
));

// Rate limit to 10MB per-minute
$mailer->registerPlugin(new Swift_Plugins_ThrottlerPlugin(
  1024 * 1024 * 10, Swift_Plugins_ThrottlerPlugin::BYTES_PER_MINUTE
));

// Continue sending as normal
for ($lotsOfRecipients as $recipient) {
  ...

  $mailer->send( ... );
}

Logger Plugin

The Logger plugins helps with debugging during the process of sending. It can help to identify why an SMTP server is rejecting addresses, or any other hard-to-find problems that may arise.

The Logger plugin comes in two parts. There's the plugin itself, along with one of a number of possible Loggers that you may choose to use. For example, the logger may output messages directly in realtime, or it may capture messages in an array.

One other notable feature is the way in which the Logger plugin changes Exception messages. If Exceptions are being thrown but the error message does not provide conclusive information as to the source of the problem (such as an ambiguous SMTP error) the Logger plugin includes the entire SMTP transcript in the error message so that debugging becomes a simpler task.

There are a few available Loggers included with Swift Mailer, but writing your own implementation is incredibly simple and is achieved by creating a short class that implements the Swift_Plugins_Logger interface.

• Swift_Plugins_Loggers_ArrayLogger: Keeps a collection of log messages inside an array. The array content can be cleared or dumped out to the screen.
• Swift_Plugins_Loggers_EchoLogger: Prints output to the screen in realtime. Handy for very rudimentary debug output.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

// Create the Mailer using any Transport
$mailer = new Swift_Mailer(
 new Swift_SmtpTransport('smtp.example.org', 25)
);

// To use the ArrayLogger
$logger = new Swift_Plugins_Loggers_ArrayLogger();
$mailer->registerPlugin(new Swift_Plugins_LoggerPlugin($logger));

// Or to use the Echo Logger
$logger = new Swift_Plugins_Loggers_EchoLogger();
$mailer->registerPlugin(new Swift_Plugins_LoggerPlugin($logger));

// Continue sending as normal
for ($lotsOfRecipients as $recipient) {
 ...

 $mailer->send( ... );
}

// Dump the log contents
// NOTE: The EchoLogger dumps in realtime so dump() does nothing for it
echo $logger->dump();

Decorator Plugin

Often there's a need to send the same message to multiple recipients, but with tiny variations such as the recipient's name being used inside the message body. The Decorator plugin aims to provide a solution for allowing these small differences.

The decorator plugin works by intercepting the sending process of Swift Mailer, reading the email address in the To: field and then looking up a set of replacements for a template.

While the use of this plugin is simple, it is probably the most commonly misunderstood plugin due to the way in which it works. The typical mistake users make is to try registering the plugin multiple times (once for each recipient) -- inside a loop for example. This is incorrect.

The Decorator plugin should be registered just once, but containing the list of all recipients prior to sending. It will use this list of recipients to find the required replacements during sending.

1
2
3
4
5
6
7

$replacements = [];
foreach ($users as $user) {
  $replacements[$user['email']] = [
    '{username}'=>$user['username'],
    '{resetcode}'=>$user['resetcode']
  ];
}

1
2
3

$decorator = new Swift_Plugins_DecoratorPlugin($replacements);

$mailer->registerPlugin($decorator);

1
2
3
4
5
6
7
8
9
10
11

$message = (new Swift_Message())
  ->setSubject('Important notice for {username}')
  ->setBody(
    "Hello {username}, you requested to reset your password.\n" .
    "Please visit https://example.com/pwreset and use the reset code {resetcode} to set a new password."
  )
  ;

foreach ($users as $user) {
  $message->addTo($user['email']);
}

1
2
3
4

Subject: Important notice for smilingsunshine2009

Hello smilingsunshine2009, you requested to reset your password.
Please visit https://example.com/pwreset and use the reset code 183457 to set a new password.

1
2
3
4

Subject: Important notice for billy-bo-bob

Hello billy-bo-bob, you requested to reset your password.
Please visit https://example.com/pwreset and use the reset code 539127 to set a new password.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

class DbReplacements implements Swift_Plugins_Decorator_Replacements {
  public function getReplacementsFor($address) {
    global $db; // Your PDO instance with a connection to your database
    $query = $db->prepare(
      "SELECT * FROM `users` WHERE `email` = ?"
    );

    $query->execute([$address]);

    if ($row = $query->fetch(PDO::FETCH_ASSOC)) {
      return [
        '{username}'=>$row['username'],
        '{resetcode}'=>$row['resetcode']
      ];
    }
  }
}

1
2
3

$decorator = new Swift_Plugins_DecoratorPlugin(new DbReplacements());

$mailer->registerPlugin($decorator);