--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/vendor/swiftmailer/doc/sending.rst Sat Sep 24 15:40:41 2011 +0200
@@ -0,0 +1,589 @@
+Sending Messages
+================
+
+Quick Reference for Sending a Message
+-------------------------------------
+
+Sending a message is very straightforward. You create a Transport, use it to
+create the Mailer, then you use the Mailer to send the message.
+
+To send a Message:
+
+* Create a Transport from one of the provided Transports --
+ ``Swift_SmtpTransport``, ``Swift_SendmailTransport``,
+ ``Swift_MailTransport`` or one of the aggregate Transports.
+
+* Create an instance of the ``Swift_Mailer`` class, using the Transport as
+ it's constructor parameter.
+
+* Create a Message.
+
+* Send the message via the ``send()`` method on the Mailer object.
+
+When using ``send()`` the message will be sent just like it would
+be sent if you used your mail client. An integer is returned which includes
+the number of successful recipients. If none of the recipients could be sent
+to then zero will be returned, which equates to a boolean
+``false``. If you set two ``To:`` recipients and
+three ``Bcc:`` recipients in the message and all of the
+recipients are delivered to successfully then the value 5 will be returned.
+
+.. code-block:: php
+
+ require_once 'lib/swift_required.php';
+
+ //Create the Transport
+ $transport = Swift_SmtpTransport::newInstance('smtp.example.org', 25)
+ ->setUsername('your username')
+ ->setPassword('your password')
+ ;
+
+ /*
+ You could alternatively use a different transport such as Sendmail or Mail:
+
+ //Sendmail
+ $transport = Swift_SendmailTransport::newInstance('/usr/sbin/sendmail -bs');
+
+ //Mail
+ $transport = Swift_MailTransport::newInstance();
+ */
+
+ //Create the Mailer using your created Transport
+ $mailer = Swift_Mailer::newInstance($transport);
+
+ //Create a message
+ $message = Swift_Message::newInstance('Wonderful Subject')
+ ->setFrom(array('john@doe.com' => 'John Doe'))
+ ->setTo(array('receiver@domain.org', 'other@domain.org' => 'A name'))
+ ->setBody('Here is the message itself')
+ ;
+
+ //Send the message
+ $result = $mailer->send($message);
+
+Transport Types
+~~~~~~~~~~~~~~~
+
+A Transport is the component which actually does the sending. You need to
+provide a Transport object to the Mailer class and there are several possible
+options.
+
+Typically you will not need to know how a Transport works under-the-surface,
+you will only need to know how to create an instance of one, and which one to
+use for your environment.
+
+The SMTP Transport
+..................
+
+The SMTP Transport sends messages over the (standardized) Simple Message Transfer
+Protocol. It can deal with encryption and authentication.
+
+The SMTP Transport, ``Swift_SmtpTransport`` is without doubt the most commonly
+used Transport because it will work on 99% of web servers (I just made that
+number up, but you get the idea). All the server needs is the ability to
+connect to a remote (or even local) SMTP server on the correct port number
+(usually 25).
+
+SMTP servers often require users to authenticate with a username and password
+before any mail can be sent to other domains. This is easily achieved using
+Swift Mailer with the SMTP Transport.
+
+SMTP is a protocol -- in other words it's a "way" of communicating a job
+to be done (i.e. sending a message). The SMTP protocol is the fundamental
+basis on which messages are delivered all over the internet 7 days a week, 365
+days a year. For this reason it's the most "direct" method of sending messages
+you can use and it's the one that will give you the most power and feedback
+(such as delivery failures) when using Swift Mailer.
+
+Because SMTP is generally run as a remote service (i.e. you connect to it over
+the network/internet) it's extremely portable from server-to-server. You can
+easily store the SMTP server address and port number in a configuration file
+within your application and adjust the settings accordingly if the code is
+moved or if the SMTP server is changed.
+
+Some SMTP servers -- Google for example -- use encryption for
+security reasons. Swift Mailer supports using both SSL and TLS encryption
+settings.
+
+
+Using the SMTP Transport
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+The SMTP Transport is easy to use. Most configuration options can be set with
+the constructor.
+
+To use the SMTP Transport you need to know which SMTP server your code needs
+to connect to. Ask your web host if you're not sure. Lots of people ask me who
+to connect to -- I really can't answer that since it's a setting that's
+extremely specific to your hosting environment.
+
+To use the SMTP Transport:
+
+* Call ``Swift_SmtpTransport::newInstance()`` with the SMTP server name and
+ optionally with a port number (defaults to 25).
+
+* Use the returned object to create the Mailer.
+
+A connection to the SMTP server will be established upon the first call to
+``send()``.
+
+.. code-block:: php
+
+ require_once 'lib/swift_required.php';
+
+ //Create the Transport
+ $transport = Swift_SmtpTransport::newInstance('smtp.example.org', 25);
+
+ //Create the Mailer using your created Transport
+ $mailer = Swift_Mailer::newInstance($transport);
+
+ /*
+ It's also possible to use multiple method calls
+
+ $transport = Swift_SmtpTransport::newInstance()
+ ->setHost('smtp.example.org')
+ ->setPort(25)
+ ;
+ */
+
+Encrypted SMTP
+^^^^^^^^^^^^^^
+
+You can use SSL or TLS encryption with the SMTP Transport by specifying it as
+a parameter or with a method call.
+
+To use encryption with the SMTP Transport:
+
+* Pass the encryption setting as a third parameter to
+ ``Swift_SmtpTransport::newInstance()``; or
+
+* Call the ``setEncryption()`` method on the Transport.
+
+A connection to the SMTP server will be established upon the first call to
+``send()``. The connection will be initiated with the correct encryption
+settings.
+
+.. note::
+
+ For SSL or TLS encryption to work your PHP installation must have
+ appropriate OpenSSL transports wrappers. You can check if "tls" and/or
+ "ssl" are present in your PHP installation by using the PHP function
+ ``stream_get_transports()``
+
+ .. code-block:: php
+
+ require_once 'lib/swift_required.php';
+
+ //Create the Transport
+ $transport = Swift_SmtpTransport::newInstance('smtp.example.org', 587, 'ssl');
+
+ //Create the Mailer using your created Transport
+ $mailer = Swift_Mailer::newInstance($transport);
+
+ /*
+ It's also possible to use multiple method calls
+
+ $transport = Swift_SmtpTransport::newInstance()
+ ->setHost('smtp.example.org')
+ ->setPort(587)
+ ->setEncryption('ssl')
+ ;
+ */
+
+SMTP with a Username and Password
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Some servers require authentication. You can provide a username and password
+with ``setUsername()`` and ``setPassword()``.
+
+To use a username and password with the SMTP Transport:
+
+* Create the Transport with ``Swift_SmtpTransport::newInstance()``.
+
+* Call the ``setUsername()`` and ``setPassword()`` methods on the Transport.
+
+Your username and password will be used to authenticate upon first connect
+when ``send()`` are first used on the Mailer.
+
+If authentication fails, an Exception of type
+``Swift_Transport_TransportException`` will be thrown.
+
+.. note::
+
+ If you need to know early whether or not authentication has failed and an
+ Exception is going to be thrown, call the ``start()`` method on the
+ created Transport.
+
+ .. code-block:: php
+
+ require_once 'lib/swift_required.php';
+
+ //Create the Transport the call setUsername() and setPassword()
+ $transport = Swift_SmtpTransport::newInstance('smtp.example.org', 25)
+ ->setUsername('username')
+ ->setPassword('password')
+ ;
+
+ //Create the Mailer using your created Transport
+ $mailer = Swift_Mailer::newInstance($transport);
+
+The Sendmail Transport
+......................
+
+The Sendmail Transport sends messages by communicating with a locally
+installed MTA -- such as ``sendmail``.
+
+The Sendmail Transport, ``Swift_SendmailTransport`` does not
+directly connect to any remote services. It is designed for Linux servers that
+have ``sendmail`` installed. The Transport starts a local
+``sendmail`` process and sends messages to it. Usually the
+``sendmail`` process will respond quickly as it spools your
+messages to disk before sending them.
+
+The Transport is named the Sendmail Transport for historical reasons
+(``sendmail`` was the "standard" UNIX tool for sending e-mail
+for years). It will send messages using other transfer agents such as Exim or
+Postfix despite its name, provided they have the relevant sendmail wrappers so
+that they can be started with the correct command-line flags.
+
+It's a common misconception that because the Sendmail Transport returns a
+result very quickly it must therefore deliver messages to recipients quickly
+-- this is not true. It's not slow by any means, but it's certainly not
+faster than SMTP when it comes to getting messages to the intended recipients.
+This is because sendmail itself sends the messages over SMTP once they have
+been quickly spooled to disk.
+
+The Sendmail Transport has the potential to be just as smart of the SMTP
+Transport when it comes to notifying Swift Mailer about which recipients were
+rejected, but in reality the majority of locally installed
+``sendmail`` instances are not configured well enough to
+provide any useful feedback. As such Swift Mailer may report successful
+deliveries where they did in fact fail before they even left your server.
+
+You can run the Sendmail Transport in two different modes specified by command
+line flags:
+
+* "``-bs``" runs in SMTP mode so theoretically it will act like the SMTP
+ Transport
+
+* "``-t``" runs in piped mode with no feedback, but theoretically faster,
+ though not advised
+
+You can think of the Sendmail Transport as a sort of asynchronous SMTP
+Transport -- though if you have problems with delivery failures you
+should try using the SMTP Transport instead. Swift Mailer isn't doing the work
+here, it's simply passing the work to somebody else (i.e.
+``sendmail``).
+
+Using the Sendmail Transport
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To use the Sendmail Transport you simply need to call
+``Swift_SendmailTransport::newInstance()`` with the command as a
+parameter.
+
+To use the Sendmail Transport you need to know where
+``sendmail`` or another MTA exists on the server. Swift Mailer
+uses a default value of ``/usr/sbin/sendmail``, which should
+work on most systems.
+
+You specify the entire command as a parameter (i.e. including the command line
+flags). Swift Mailer supports operational modes of "``-bs``"
+(default) and "``-t``".
+
+.. note::
+
+ If you run sendmail in "``-t``" mode you will get no feedback as to
+ whether or not sending has succeeded. Use "``-bs``" unless you have a
+ reason not to.
+
+To use the Sendmail Transport:
+
+* Call ``Swift_SendmailTransport::newInstance()`` with the command, including
+ the correct command line flags. The default is to use ``/usr/sbin/sendmail
+ -bs`` if this is not specified.
+
+* Use the returned object to create the Mailer.
+
+A sendmail process will be started upon the first call to ``send()``. If the
+process cannot be started successfully an Exception of type
+``Swift_Transport_TransportException`` will be thrown.
+
+.. code-block:: php
+
+ require_once 'lib/swift_required.php';
+
+ //Create the Transport
+ $transport = Swift_SendmailTransport::newInstance('/usr/sbin/exim -bs');
+
+ //Create the Mailer using your created Transport
+ $mailer = Swift_Mailer::newInstance($transport);
+
+The Mail Transport
+..................
+
+The Mail Transport sends messages by delegating to PHP's internal
+``mail()`` function.
+
+In my experience -- and others' -- the ``mail()``
+function is not particularly predictable, or helpful.
+
+Quite notably, the ``mail()`` function behaves entirely
+differently between Linux and Windows servers. On linux it uses
+``sendmail``, but on Windows it uses SMTP.
+
+In order for the ``mail()`` function to even work at all
+``php.ini`` needs to be configured correctly, specifying the
+location of sendmail or of an SMTP server.
+
+The problem with ``mail()`` is that it "tries" to simplify things
+to the point that it actually makes things more complex due to poor interface
+design. The developers of Swift Mailer have gone to a lot of effort to make
+the Mail Transport work with a reasonable degree of consistency.
+
+Serious drawbacks when using this Transport are:
+
+* Unpredictable message headers
+
+* Lack of feedback regarding delivery failures
+
+* Lack of support for several plugins that require real-time delivery feedback
+
+It's a last resort, and we say that with a passion!
+
+Using the Mail Transport
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+To use the Mail Transport you simply need to call
+``Swift_MailTransport::newInstance()``. It's unlikely you'll need
+to configure the Transport.
+
+To use the Mail Transport:
+
+* Call ``Swift_MailTransport::newInstance()``.
+
+* Use the returned object to create the Mailer.
+
+Messages will be sent using the ``mail()`` function.
+
+.. note::
+
+ The ``mail()`` function can take a ``$additional_parameters`` parameter.
+ Swift Mailer sets this to "``-f%s``" by default, where the "%s" is
+ substituted with the address of the sender (via a ``sprintf()``) at send
+ time. You may override this default by passing an argument to
+ ``newInstance()``.
+
+ .. code-block:: php
+
+ require_once 'lib/swift_required.php';
+
+ //Create the Transport
+ $transport = Swift_MailTransport::newInstance();
+
+ //Create the Mailer using your created Transport
+ $mailer = Swift_Mailer::newInstance($transport);
+
+Available Methods for Sending Messages
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The Mailer class offers two methods for sending Messages -- ``send()``.
+Each behaves in a slightly different way.
+
+When a message is sent in Swift Mailer, the Mailer class communicates with
+whichever Transport class you have chosen to use.
+
+Each recipient in the message should either be accepted or rejected by the
+Transport. For example, if the domain name on the email address is not
+reachable the SMTP Transport may reject the address because it cannot process
+it. Whichever method you use -- ``send()`` -- Swift Mailer will return
+an integer indicating the number of accepted recipients.
+
+.. note::
+
+ It's possible to find out which recipients were rejected -- we'll
+ cover that later in this chapter.
+
+Using the ``send()`` Method
+...........................
+
+The ``send()`` method of the ``Swift_Mailer`` class
+sends a message using exactly the same logic as your Desktop mail client would
+use. Just pass it a Messgae and get a result.
+
+To send a Message with ``send()``:
+
+* Create a Transport from one of the provided Transports --
+ ``Swift_SmtpTransport``, ``Swift_SendmailTransport``,
+ ``Swift_MailTransport`` or one of the aggregate Transports.
+
+* Create an instance of the ``Swift_Mailer`` class, using the Transport as
+ it's constructor parameter.
+
+* Create a Message.
+
+* Send the message via the ``send()`` method on the Mailer object.
+
+The message will be sent just like it would be sent if you used your mail
+client. An integer is returned which includes the number of successful
+recipients. If none of the recipients could be sent to then zero will be
+returned, which equates to a boolean ``false``. If you set two
+``To:`` recipients and three ``Bcc:`` recipients in
+the message and all of the recipients are delivered to successfully then the
+value 5 will be returned.
+
+.. code-block:: php
+
+ require_once 'lib/swift_required.php';
+
+ //Create the Transport
+ $transport = Swift_SmtpTransport::newInstance('localhost', 25);
+
+ //Create the Mailer using your created Transport
+ $mailer = Swift_Mailer::newInstance($transport);
+
+ //Create a message
+ $message = Swift_Message::newInstance('Wonderful Subject')
+ ->setFrom(array('john@doe.com' => 'John Doe'))
+ ->setTo(array('receiver@domain.org', 'other@domain.org' => 'A name'))
+ ->setBody('Here is the message itself')
+ ;
+
+ //Send the message
+ $numSent = $mailer->send($message);
+
+ printf("Sent %d messages\n", $numSent);
+
+ /* Note that often that only the boolean equivalent of the
+ return value is of concern (zero indicates FALSE)
+
+ if ($mailer->send($message))
+ {
+ echo "Sent\n";
+ }
+ else
+ {
+ echo "Failed\n";
+ }
+
+ */
+
+Sending Emails in Batch
+.......................
+
+If you want to send a separate message to each recipient so that only their
+own address shows up in the ``To:`` field, follow the following recipe:
+
+* Create a Transport from one of the provided Transports --
+ ``Swift_SmtpTransport``, ``Swift_SendmailTransport``,
+ ``Swift_MailTransport`` or one of the aggregate Transports.
+
+* Create an instance of the ``Swift_Mailer`` class, using the Transport as
+ it's constructor parameter.
+
+* Create a Message.
+
+* Iterate over the recipients and send message via the ``send()`` method on
+ the Mailer object.
+
+Each recipient of the messages receives a different copy with only their own
+email address on the ``To:`` field.
+
+.. note::
+
+ In the following example, two emails are sent. One to each of
+ ``receiver@domain.org`` and ``other@domain.org``. These recipients will
+ not be aware of each other.
+
+ .. code-block:: php
+
+ require_once 'lib/swift_required.php';
+
+ //Create the Transport
+ $transport = Swift_SmtpTransport::newInstance('localhost', 25);
+
+ //Create the Mailer using your created Transport
+ $mailer = Swift_Mailer::newInstance($transport);
+
+ //Create a message
+ $message = Swift_Message::newInstance('Wonderful Subject')
+ ->setFrom(array('john@doe.com' => 'John Doe'))
+ ->setBody('Here is the message itself')
+ ;
+
+ //Send the message
+ $failedRecipients = array();
+ $numSent = 0;
+ $to = array('receiver@domain.org', 'other@domain.org' => 'A name');
+
+ foreach ($to as $address => $name)
+ {
+ $message->setTo(array($address => $name));
+ $numSent += $this->send($message, $failedRecipients);
+ }
+
+ printf("Sent %d messages\n", $numSent);
+
+Finding out Rejected Addresses
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+It's possible to get a list of addresses that were rejected by the Transport
+by using a by-reference parameter to ``send()``.
+
+As Swift Mailer attempts to send the message to each address given to it, if a
+recipient is rejected it will be added to the array. You can pass an existing
+array, otherwise one will be created by-reference.
+
+Collecting the list of recipients that were rejected can be useful in
+circumstances where you need to "prune" a mailing list for example when some
+addresses cannot be delivered to.
+
+Getting Failures By-reference
+.............................
+
+Collecting delivery failures by-reference with the ``send()`` method is as
+simple as passing a variable name to the method call.
+
+To get failed recipients by-reference:
+
+* Pass a by-reference variable name to the ``send()`` method of the Mailer
+ class.
+
+If the Transport rejects any of the recipients, the culprit addresses will be
+added to the array provided by-reference.
+
+.. note::
+
+ If the variable name does not yet exist, it will be initialized as an
+ empty array and then failures will be added to that array. If the variable
+ already exists it will be type-cast to an array and failures will be added
+ to it.
+
+ .. code-block:: php
+
+ $mailer = Swift_Mailer::newInstance( ... );
+
+ $message = Swift_Message::newInstance( ... )
+ ->setFrom( ... )
+ ->setTo(array(
+ 'receiver@bad-domain.org' => 'Receiver Name',
+ 'other@domain.org' => 'A name',
+ 'other-receiver@bad-domain.org' => 'Other Name'
+ ))
+ ->setBody( ... )
+ ;
+
+ //Pass a variable name to the send() method
+ if (!$mailer->send($message, $failures))
+ {
+ echo "Failures:";
+ print_r($failures);
+ }
+
+ /*
+ Failures:
+ Array (
+ 0 => receiver@bad-domain.org,
+ 1 => other-receiver@bad-domain.org
+ )
+ */