hdabo_sf: comparison vendor/swiftmailer/doc/plugins.rst

equal deleted inserted replaced

--1:000000000000
+:7f95f8617b0b
+Plugins
+=======
+Plugins are provided with Swift Mailer and can be used to extend the behavior
+of the library in ways that simple class inheritance would be more complex.
+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.
+Using the AntiFlood Plugin
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+The AntiFlood Plugin -- like all plugins -- is added with the Mailer
+class' ``registerPlugin()`` method. It takes two constructor
+parameters: the number of emails to pause after, and optionally the number of
+seconds to pause for.
+To use the AntiFlood plugin:
+* Create an instance of the Mailer using any Transport you choose.
+* Create an instance of the ``Swift_Plugins_AntiFloodPlugin`` class, passing
+in one or two constructor parameters.
+* Register the plugin using the Mailer's ``registerPlugin()`` method.
+* Continue using Swift Mailer to send messages as normal.
+When Swift Mailer sends messages it will count the number of messages that
+have been sent since the last re-connect. Once the number hits your specified
+threshold it will disconnect and re-connect, optionally pausing for a
+specified amount of time.
+.. code-block:: php
+require_once 'lib/swift_required.php';
+//Create the Mailer using any Transport
+$mailer = Swift_Mailer::newInstance(
+Swift_SmtpTransport::newInstance('smtp.example.org', 25)
+);
+//Use AntiFlood to re-connect after 100 emails
+$mailer->registerPlugin(new Swift_Plugins_AntiFloodPlugin(100));
+//Or 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.
+Using the Throttler Plugin
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+The Throttler Plugin -- like all plugins -- is added with the Mailer
+class' ``registerPlugin()`` method. It has two required
+constructor parameters that tell it how to do its rate-limiting.
+To use the Throttler plugin:
+* Create an instance of the Mailer using any Transport you choose.
+* Create an instance of the ``Swift_Plugins_ThrottlerPlugin`` class, passing
+the number of emails, or bytes you wish to limit by, along with the mode
+you're using.
+* Register the plugin using the Mailer's ``registerPlugin()`` method.
+* Continue using Swift Mailer to send messages as normal.
+When Swift Mailer sends messages it will keep track of the rate at which
+sending messages is occuring. If it realises that sending is happening too
+fast, it will cause your program to ``sleep()`` for enough time
+to average out the rate.
+.. code-block:: php
+require_once 'lib/swift_required.php';
+//Create the Mailer using any Transport
+$mailer = Swift_Mailer::newInstance(
+Swift_SmtpTransport::newInstance('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.
+Using the Logger Plugin
+.......................
+The Logger Plugin -- like all plugins -- is added with the Mailer
+class' ``registerPlugin()`` method. It accepts an instance of
+``Swift_Plugins_Logger`` in its constructor.
+To use the Logger plugin:
+* Create an instance of the Mailer using any Transport you choose.
+* Create an instance of the a Logger implementation of
+``Swift_Plugins_Logger``.
+* Create an instance of the ``Swift_Plugins_LoggerPlugin`` class, passing the
+created Logger instance to its constructor.
+* Register the plugin using the Mailer's ``registerPlugin()`` method.
+* Continue using Swift Mailer to send messages as normal.
+* Dump the contents of the log with the logger's ``dump()`` method.
+When Swift Mailer sends messages it will keep a log of all the interactions
+with the underlying Transport being used. Depending upon the Logger that has
+been used the behaviour will differ, but all implementations offer a way to
+get the contents of the log.
+.. code-block:: php
+require_once 'lib/swift_required.php';
+//Create the Mailer using any Transport
+$mailer = Swift_Mailer::newInstance(
+Swift_SmtpTransport::newInstance('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.
+Using the Decorator Plugin
+..........................
+To use the Decorator plugin, simply create an associative array of
+replacements based on email addresses and then use the mailer's
+``registerPlugin()`` method to add the plugin.
+First create an associative array of replacements based on the email addresses
+you'll be sending the message to.
+.. note::
+The replacements array becomes a 2-dimensional array whose keys are the
+email addresses and whose values are an associative array of replacements
+for that email address. The curly braces used in this example can be any
+type of syntax you choose, provided they match the placeholders in your
+email template.
+.. code-block:: php
+$replacements = array();
+foreach ($users as $user) {
+$replacements[$user['email']] = array(
+'{username}'=>$user['username'],
+'{password}'=>$user['password']
+);
+}
+Now create an instance of the Decorator plugin using this array of
+replacements and then register it with the Mailer. Do this only once!
+.. code-block:: php
+$decorator = new Swift_Plugins_DecoratorPlugin($replacements);
+$mailer->registerPlugin($decorator);
+When you create your message, replace elements in the body (and/or the subject
+line) with your placeholders.
+.. code-block:: php
+$message = Swift_Message::newInstance()
+->setSubject('Important notice for {username}')
+->setBody(
+"Hello {username}, we have reset your password to {password}\n" .
+"Please log in and change it at your earliest convenience."
+)
+;
+foreach ($users as $user) {
+$message->addTo($user['email']);
+}
+When you send this message to each of your recipients listed in your
+``$replacements`` array they will receive a message customized
+for just themselves. For example, the message used above when received may
+appear like this to one user:
+.. code-block:: text
+Subject: Important notice for smilingsunshine2009
+Hello smilingsunshine2009, we have reset your password to rainyDays
+Please log in and change it at your earliest convenience.
+While another use may receive the message as:
+.. code-block:: text
+Subject: Important notice for billy-bo-bob
+Hello billy-bo-bob, we have reset your password to dancingOctopus
+Please log in and change it at your earliest convenience.
+While the decorator plugin provides a means to solve this problem, there are
+various ways you could tackle this problem without the need for a plugin.
+We're trying to come up with a better way ourselves and while we have several
+(obvious) ideas we don't quite have the perfect solution to go ahead and
+implement it. Watch this space.
+Providing Your Own Replacements Lookup for the Decorator
+........................................................
+Filling an array with replacements may not be the best solution for providing
+replacement information to the decorator. If you have a more elegant algorithm
+that performs replacement lookups on-the-fly you may provide your own
+implementation.
+Providing your own replacements lookup implementation for the Decorator is
+simply a matter of passing an instance of
+``Swift_Plugins_Decorator_Replacements`` to the decorator
+plugin's constructor, rather than passing in an array.
+The Replacements interface is very simple to implement since it has just one
+method: ``getReplacementsFor($address)``.
+Imagine you want to look up replacements from a database on-the-fly, you might
+provide an implementation that does this. You need to create a small class.
+.. code-block:: php
+class DbReplacements implements Swift_Plugins_Decorator_Replacements {
+public function getReplacementsFor($address) {
+$sql = sprintf(
+"SELECT * FROM user WHERE email = '%s'",
+mysql_real_escape_string($address)
+);
+$result = mysql_query($sql);
+if ($row = mysql_fetch_assoc($result)) {
+return array(
+'{username}'=>$row['username'],
+'{password}'=>$row['password']
+);
+}
+}
+}
+Now all you need to do is pass an instance of your class into the Decorator
+plugin's constructor instead of passing an array.
+.. code-block:: php
+$decorator = new Swift_Plugins_DecoratorPlugin(new DbReplacements());
+$mailer->registerPlugin($decorator);
+For each message sent, the plugin will call your class'
+``getReplacementsFor()`` method to find the array of replacements
+it needs.
+.. note::
+If your lookup algorithm is case sensitive, you should transform the
+``$address`` argument as appropriate -- for example by passing it
+through ``strtolower()``.