Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

converted docs to ReST

  • Loading branch information...
commit 478b2d44c5556a84438e1accbcfe55dab1cd266a 1 parent 79fe791
@fabpot fabpot authored
View
26 docs/book/en/01-Introduction.markdown → doc/01-Introduction.rst
@@ -4,11 +4,6 @@ Introduction
Swift Mailer is a component-based library for sending e-mails from PHP
applications.
->**NOTE**
->This book refers to version 4.0 of the Swift Mailer library. If you are looking
->for information about (the now deprecated) version 3, you should refer to the
->old wiki found [online][1].
-
Organization of this Book
-------------------------
@@ -32,7 +27,8 @@ projects. We will also use diagrams where appropriate, and where we believe
readers may find it helpful we will discuss some related theory, including
reference to certain documents you are able to find online.
-### Code Samples
+Code Samples
+------------
Code samples presented in this book will be displayed on a different colored
background in a monospaced font. Samples are not to be taken as copy & paste
@@ -42,9 +38,8 @@ Code examples are used through the book to clarify what is written in text.
They will sometimes be usable as-is, but they should always be taken as
outline/pseudo code only.
-A code sample will look like this:
+A code sample will look like this::
- [php]
class AClass
{
...
@@ -58,11 +53,11 @@ A code sample will look like this:
*/
-The presence of 3 dots `...` in a code sample indicates that we have left out
-a chunk of the code for brevity, they are not actually part of the code.
+The presence of 3 dots ``...`` in a code sample indicates that we have left
+out a chunk of the code for brevity, they are not actually part of the code.
-We will often place multi-line comments `/* ... */` in the code so that we can
-show alternative ways of achieving the same result.
+We will often place multi-line comments ``/* ... */`` in the code so that we
+can show alternative ways of achieving the same result.
You should read the code examples given and try to understand them. They are
kept concise so that you are not overwhelmed with information.
@@ -74,8 +69,8 @@ Swift Mailer began back in 2005 as a one-class project for sending mail over
SMTP. It has since grown into the flexible component-based library that is in
development today.
-Chris Corbyn first posted Swift Mailer on a web [forum][2] asking for comments
-from other developers. It was never intended as a fully supported open source
+Chris Corbyn first posted Swift Mailer on a web forum asking for comments from
+other developers. It was never intended as a fully supported open source
project, but members of the forum began to adopt it and make use of it.
Very quickly feature requests were coming for the ability to add attachments
@@ -138,6 +133,3 @@ Embrace the structure of the library and use the components it offers to your
advantage. Learning what the components do, rather than blindly copying and
pasting existing code will put you in a great position to build a powerful
application!
-
-[1]: http://swiftmailer.org/wikidocs/
-[2]: http://forums.devnetwork.net/
View
161 doc/02-Overview.rst
@@ -0,0 +1,161 @@
+Library Overview
+================
+
+Most features (and more) of your every day mail client software are provided
+by Swift Mailer, using object-oriented PHP code as the interface.
+
+In this chapter we will take a short tour of the various components, which put
+together form the Swift Mailer library as a whole. You will learn key
+terminology used throughout the rest of this book and you will gain a little
+understanding of the classes you will work with as you integrate Swift Mailer
+into your application.
+
+This chapter is intended to prepare you for the information contained in the
+subsequent chapters of this book. You may choose to skip this chapter if you
+are fairly technically minded, though it is likely to save you some time in
+the long run if you at least read between the lines here.
+
+System Requirements
+-------------------
+
+The basic requirements to operate Swift Mailer are extremely minimal and
+easily achieved. Historically, Swift Mailer has supported both PHP 4 and PHP 5
+by following a parallel development workflow. Now in it's fourth major
+version, and Swift Mailer operates on servers running PHP 5.2 or higher.
+
+The library aims to work with as many PHP 5 projects as possible:
+
+* PHP 5.2 or higher, with the SPL extension (standard)
+
+* Limited network access to connect to remote SMTP servers
+
+* 8 MB or more memory limit (Swift Mailer uses around 2 MB)
+
+Component Breakdown
+-------------------
+
+Swift Mailer is made up of many classes. Each of these classes can be grouped
+into a general "component" group which describes the task it is designed to
+perform.
+
+We'll take a brief look at the components which form Swift Mailer in this
+section of the book.
+
+The Mailer
+~~~~~~~~~~
+
+The mailer class, ``Swift_Mailer`` is the central class in the library where
+all of the other components meet one another. ``Swift_Mailer`` acts as a sort
+of message dispatcher, communicating with the underlying Transport to deliver
+your Message to all intended recipients.
+
+If you were to dig around in the source code for Swift Mailer you'd notice
+that ``Swift_Mailer`` itself is pretty bare. It delegates to other objects for
+most tasks and in theory, if you knew the internals of Swift Mailer well you
+could by-pass this class entirely. We wouldn't advise doing such a thing
+however -- there are reasons this class exists:
+
+* for consistency, regardless of the Transport used
+
+* to provide abstraction from the internals in the event internal API changes
+ are made
+
+* to provide convenience wrappers around aspects of the internal API
+
+An instance of ``Swift_Mailer`` is created by the developer before sending any
+Messages.
+
+Transports
+~~~~~~~~~~
+
+Transports are the classes in Swift Mailer that are responsible for
+communicating with a service in order to deliver a Message. There are several
+types of Transport in Swift Mailer, all of which implement the Swift_Transport
+interface and offer underlying start(), stop() and send() methods.
+
+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.
+
++---------------------------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+
+| Class | Features | Pros/cons |
++=================================+=============================================================================================+===============================================================================================================================================+
+| ``Swift_SmtpTransport`` | Sends messages over SMTP; Supports Authentication; Supports Encryption | Very portable; Pleasingly predictable results; Provides good feedback |
++---------------------------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+
+| ``Swift_SendmailTransport`` | Communicates with a locally installed ``sendmail`` executable (Linux/UNIX) | Quick time-to-run; Provides less-accurate feedback than SMTP; Requires ``sendmail`` installation |
++---------------------------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+
+| ``Swift_MailTransport`` | Uses PHP's built-in ``mail()`` function | Very portable; Potentially unpredictable results; Provides extremely weak feedback |
++---------------------------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+
+| ``Swift_LoadBalancedTransport`` | Cycles through a collection of the other Transports to manage load-reduction | Provides graceful fallback if one Transport fails (e.g. an SMTP server is down); Keeps the load on remote services down by spreading the work |
++---------------------------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+
+| ``Swift_FailoverTransport`` | Works in conjunction with a collection of the other Transports to provide high-availability | Provides graceful fallback if one Transport fails (e.g. an SMTP server is down) |
++---------------------------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+
+
+MIME Entities
+~~~~~~~~~~~~~
+
+Everything that forms part of a Message is called a MIME Entity. All MIME
+entities in Swift Mailer share a common set of features. There are various
+types of MIME entity that serve different purposes such as Attachments and
+MIME parts.
+
+An e-mail message is made up of several relatively simple entities that are
+combined in different ways to achieve different results. All of these entities
+have the same fundamental outline but serve a different purpose. The Message
+itself can be defined as a MIME entity, an Attachment is a MIME entity, all
+MIME parts are MIME entities -- and so on!
+
+The basic units of each MIME entity -- be it the Message itself, or an
+Attachment -- are its Headers and its body:
+
+.. code-block:: text
+
+ Other-Header: Another value
+
+ The body content itself
+
+The Headers of a MIME entity, and its body must conform to some strict
+standards defined by various RFC documents. Swift Mailer ensures that these
+specifications are followed by using various types of object, including
+Encoders and different Header types to generate the entity.
+
+Each MIME component implements the base ``Swift_Mime_MimeEntity`` interface,
+which offers methods for retrieving Headers, adding new Headers, changing the
+Encoder, updating the body and so on!
+
+All MIME entities have one Header in common -- the Content-Type Header,
+updated with the entity's ``setContentType()`` method.
+
+Encoders
+~~~~~~~~
+
+Encoders are used to transform the content of Messages generated in Swift
+Mailer into a format that is safe to send across the internet and that
+conforms to RFC specifications.
+
+Generally speaking you will not need to interact with the Encoders in Swift
+Mailer -- the correct settings will be handled by the library itself.
+However they are probably worth a brief mention in the event that you do want
+to play with them.
+
+Both the Headers and the body of all MIME entities (including the Message
+itself) use Encoders to ensure the data they contain can be sent over the
+internet without becoming corrupted or misinterpreted.
+
+There are two types of Encoder: Base64 and Quoted-Printable.
+
+Plugins
+~~~~~~~
+
+Plugins exist to extend, or modify the behaviour of Swift Mailer. They respond
+to Events that are fired within the Transports during sending.
+
+There are a number of Plugins provided as part of the base Swift Mailer
+package and they all follow a common interface to respond to Events fired
+within the library. Interfaces are provided to "listen" to each type of Event
+fired and to act as desired when a listened-to Event occurs.
+
+Although several plugins are provided with Swift Mailer out-of-the-box, the
+Events system has been specifically designed to make it easy for experienced
+object-oriented developers to write their own plugins in order to achieve
+goals that may not be possible with the base library.
View
106 docs/book/en/03-Installing.markdown → doc/03-Installing.rst
@@ -10,28 +10,31 @@ Installing from a Package
Most users will download a package from the Swift Mailer website and install
Swift Mailer using this.
-If you downloaded Swift Mailer as a `.tar.gz` or
-`.zip` file installation is as simple as extracting the archive
+If you downloaded Swift Mailer as a ``.tar.gz`` or
+``.zip`` file installation is as simple as extracting the archive
and uploading it to your web server.
-### Extracting the Library
+Extracting the Library
+~~~~~~~~~~~~~~~~~~~~~~
You extract the archive by using your favorite unarchiving tool such as
-`tar` or 7-Zip.
+``tar`` or 7-Zip.
You will need to have access to a program that can open uncompress the
archive. On Windows computers, 7-Zip will work. On Mac and Linux systems you
-can use `tar` on the command line.
+can use ``tar`` on the command line.
To extract your downloaded package:
- * Use the "extract" facility of your archiving software.
+* Use the "extract" facility of your archiving software.
The source code will be placed into a directory with the same name as the
archive (e.g. Swift-4.0.0-b1).
The following example shows the process on Mac OS X and Linux systems using
-the `tar` command.
+the ``tar`` command.
+
+.. code-block:: bash
chrisbook:build chris$ ls
Swift-4.0.0-dev.tar.gz
@@ -65,31 +68,37 @@ you want to keep up-to-date with ease.
Swift Mailer's source code is kept in a git repository at github.com so you
can get the source directly from the repository.
->**NOTE**
->You do not need to have git installed to use Swift Mailer from github. If you don't
->have git installed, go to [github][1] and click the "Download" button.
+.. note::
+
+ You do not need to have git installed to use Swift Mailer from github. If
+ you don't have git installed, go to `github`_ and click the "Download"
+ button.
-### Cloning the Repository
+Cloning the Repository
+~~~~~~~~~~~~~~~~~~~~~~
The repository can be cloned from git://github.com/swiftmailer/swiftmailer.git
-using the `git clone` command.
+using the ``git clone`` command.
-You will need to have `git` installed before you can use the
-`git clone` command.
+You will need to have ``git`` installed before you can use the
+``git clone`` command.
To clone the repository:
- * Open your favorite terminal environment (command line).
+* Open your favorite terminal environment (command line).
- * Move to the directory you want to clone to.
+* Move to the directory you want to clone to.
- * Run the command `git clone git://github.com/swiftmailer/swiftmailer.git swiftmailer`.
+* Run the command ``git clone git://github.com/swiftmailer/swiftmailer.git
+ swiftmailer``.
The source code will be downloaded into a directory called "swiftmailer".
The example shows the process on a UNIX-like system such as Linux, BSD or Mac
OS X.
+.. code-block:: bash
+
chrisbook:~ chris$ cd source_code/
chrisbook:source_code chris$ git clone git://github.com/swiftmailer/swiftmailer.git swiftmailer
Initialized empty Git repository in /Users/chris/source_code/swiftmailer/.git/
@@ -117,39 +126,42 @@ You will need FTP, rsync or similar software installed in order to upload the
To upload Swift Mailer:
- * Open your FTP program, or a command line if you prefer rsync/scp.
+* Open your FTP program, or a command line if you prefer rsync/scp.
- * Upload the "lib/" directory to your hosting account.
+* Upload the "lib/" directory to your hosting account.
The files needed to use Swift Mailer should now be accessible to PHP on your
host.
The following example shows show you can upload the files using
-`rsync` on Linux or OS X.
-
->**NOTE**
->You do not need to place the files inside your web root. They only need to be in a place
->where your PHP scripts can "include" them.
-
- chrisbook:Swift-4.0.0-dev chris$ rsync -rvz lib d11wtq@swiftmailer.org:swiftmailer
- building file list ... done
- created directory swiftmailer
- lib/
- lib/mime_types.php
- lib/preferences.php
- lib/swift_required.php
- lib/classes/
- lib/classes/Swift/
- lib/classes/Swift/Attachment.php
- lib/classes/Swift/CharacterReader.php
- ... etc etc ...
- lib/dependency_maps/
- lib/dependency_maps/cache_deps.php
- lib/dependency_maps/mime_deps.php
- lib/dependency_maps/transport_deps.php
-
- sent 151692 bytes received 2974 bytes 5836.45 bytes/sec
- total size is 401405 speedup is 2.60
- chrisbook:Swift-4.0.0-dev chris$
-
-[1]: http://github.com/swiftmailer/swiftmailer
+``rsync`` on Linux or OS X.
+
+.. note::
+
+ You do not need to place the files inside your web root. They only need to be in a place
+ where your PHP scripts can "include" them.
+
+ .. code-block: bash
+
+ chrisbook:Swift-4.0.0-dev chris$ rsync -rvz lib d11wtq@swiftmailer.org:swiftmailer
+ building file list ... done
+ created directory swiftmailer
+ lib/
+ lib/mime_types.php
+ lib/preferences.php
+ lib/swift_required.php
+ lib/classes/
+ lib/classes/Swift/
+ lib/classes/Swift/Attachment.php
+ lib/classes/Swift/CharacterReader.php
+ ... etc etc ...
+ lib/dependency_maps/
+ lib/dependency_maps/cache_deps.php
+ lib/dependency_maps/mime_deps.php
+ lib/dependency_maps/transport_deps.php
+
+ sent 151692 bytes received 2974 bytes 5836.45 bytes/sec
+ total size is 401405 speedup is 2.60
+ chrisbook:Swift-4.0.0-dev chris$
+
+.. _`github`: http://github.com/swiftmailer/swiftmailer
View
32 docs/book/en/04-Getting-Help.markdown → doc/04-Getting-Help.rst
@@ -4,20 +4,18 @@ Getting Help
There are a number of ways you can get help when using Swift Mailer, depending
upon the nature of your problem. For bug reports and feature requests create a
new ticket in Lighthouse. For general advice ask on the Google Group
-(swiftmailer), or make a post on the forum at forums.devnetwork.net.
+(swiftmailer).
-Submitting Bugs & Feature Requests
---------------------------------------
+Submitting Bugs & Feature Requests
+----------------------------------
Bugs and feature requests should be posted on Lighthouse.
If you post a bug or request a feature in the forum, or on the Google Group
-you will most likely be asked to create a ticket in [Lighthouse][1] since it is the
-simply not feasible to manage such requests from a number of a different
+you will most likely be asked to create a ticket in `Lighthouse`_ since it is
+the simply not feasible to manage such requests from a number of a different
sources.
-<image href="images/docs/lighthouse.png" placement="break" />
-
When you go to Lighthouse you will be asked to create a username and password
before you can create a ticket. This is free and takes very little time.
@@ -33,7 +31,7 @@ Lighthouse will update you when work is performed on your ticket.
Ask on the Google Group
-----------------------
-You can seek advice at Google Groups, within the "swiftmailer" [group][2].
+You can seek advice at Google Groups, within the "swiftmailer" `group`_.
You can post messages to this group if you want help, or there's something you
wish to discuss with the developers and with other users.
@@ -42,19 +40,5 @@ This is probably the fastest way to get help since it is primarily email-based
for most users, though bug reports should not be posted here since they may
not be resolved.
-Ask on the Forum
-----------------
-
-You can create a thread in the web forum at forums.devnetwork.net.
-
-Swift Mailer has it's own [board][3] on the Developer's Network.
-
-If you post messages here they will be read by the developers and by other
-members of the forum.
-
-This forum is a PHP forum, so you may post in the other boards within the
-forum if you need more general help with PHP itself.
-
-[1]: http://swiftmailer.lighthouseapp.com/
-[2]: http://groups.google.com/group/swiftmailer
-[3]: http://forums.devnetwork.net/viewforum.php?f=52
+.. _`Lighthouse`: http://swiftmailer.lighthouseapp.com/
+.. _`group`: http://groups.google.com/group/swiftmailer
View
30 doc/05-Including-SwiftMailer.rst
@@ -0,0 +1,30 @@
+Including Swift Mailer (Autoloading)
+====================================
+
+Swift Mailer uses an auto-loader so the only file you need to include is the
+``lib/swift_required.php`` file.
+
+To use Swift Mailer's autoloader:
+
+* Put Swift Mailer somewhere accessible to your PHP scripts (this does not
+ need to be in the web root).
+
+* Include, or require the ``lib/swift_required.php`` file.
+
+* Follow the remainder of the documentation for using the available
+ components.
+
+.. note::
+
+ While Swift Mailer's autoloader is designed to play nicely with other
+ autoloaders, sometimes you may have a need to avoid using Swift Mailer's
+ autoloader and use your own instead. Include the ``swift_init.php``
+ instead of the ``swift_required.php`` if you need to do this. The very
+ minimum include is the ``swift_init.php`` file since Swift Mailer will not
+ work without the dependency injection this file sets up:
+
+ .. code-block:: php
+
+ require_once '/path/to/swift-mailer/lib/swift_required.php';
+
+ /* rest of code goes here */
View
976 doc/06-Creating-Messages.rst
@@ -0,0 +1,976 @@
+Creating Messages
+=================
+
+Creating messages in Swift Mailer is done by making use of the various MIME
+entities provided with the library. Complex messages can be quickly created
+with very little effort.
+
+Quick Reference for Creating a Message
+---------------------------------------
+
+You can think of creating a Message as being similar to the steps you perform
+when you click the Compose button in your mail client. You give it a subject,
+specify some recipients, add any attachments and write your message.
+
+To create a Message:
+
+* Call the ``newInstance()`` method of ``Swift_Message``.
+
+* Set your sender address (``From:``) with ``setFrom()`` or ``setSender()``.
+
+* Set a subject line with ``setSubject()``.
+
+* Set recipients with ``setTo()``, ``setCc()`` and/or ``setBcc()``.
+
+* Set a body with ``setBody()``.
+
+* Add attachments with ``attach()``.
+
+.. code-block:: php
+
+ require_once 'lib/swift_required.php';
+
+ //Create the message
+ $message = Swift_Message::newInstance()
+
+ //Give the message a subject
+ ->setSubject('Your subject')
+
+ //Set the From address with an associative array
+ ->setFrom(array('john@doe.com' => 'John Doe'))
+
+ //Set the To addresses with an associative array
+ ->setTo(array('receiver@domain.org', 'other@domain.org' => 'A name'))
+
+ //Give it a body
+ ->setBody('Here is the message itself')
+
+ //And optionally an alternative body
+ ->addPart('<q>Here is the message itself</q>', 'text/html')
+
+ //Optionally add any attachments
+ ->attach(Swift_Attachment::fromPath('my-document.pdf'))
+ ;
+
+Message Basics
+--------------
+
+A message is a container for anything you want to send to somebody else. There
+are several basic aspects of a message that you should know.
+
+An e-mail message is made up of several relatively simple entities that are
+combined in different ways to achieve different results. All of these entities
+have the same fundamental outline but serve a different purpose. The Message
+itself can be defined as a MIME entity, an Attachment is a MIME entity, all
+MIME parts are MIME entities -- and so on!
+
+The basic units of each MIME entity -- be it the Message itself, or an
+Attachment -- are its Headers and its body:
+
+.. code-block:: text
+
+ Header-Name: A header value
+ Other-Header: Another value
+
+ The body content itself
+
+The Headers of a MIME entity, and its body must conform to some strict
+standards defined by various RFC documents. Swift Mailer ensures that these
+specifications are followed by using various types of object, including
+Encoders and different Header types to generate the entity.
+
+The Structure of a Message
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Of all of the MIME entities, a message -- ``Swift_Message``
+is the largest and most complex. It has many properties that can be updated
+and it can contain other MIME entities -- attachments for example --
+nested inside it.
+
+A Message has a lot of different Headers which are there to present
+information about the message to the recipients' mail client. Most of these
+headers will be familiar to the majority of users, but we'll list the basic
+ones. Although it's possible to work directly with the Headers of a Message
+(or other MIME entity), the standard Headers have accessor methods provided to
+abstract away the complex details for you. For example, although the Date on a
+message is written with a strict format, you only need to pass a UNIX
+timestamp to ``setDate()``.
+
++-------------------------------+------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------+
+| Header | Description | Accessors |
++===============================+====================================================================================================================================+=============================================+
+| ``Message-ID`` | Identifies this message with a unique ID, usually containing the domain name and time generated | ``getId()`` / ``setId()`` |
++-------------------------------+------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------+
+| ``Return-Path`` | Specifies where bounces should go (Swift Mailer reads this for other uses) | ``getReturnPath()`` / ``setReturnPath()`` |
++-------------------------------+------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------+
+| ``From`` | Specifies the address of the person who the message is from. This can be multiple addresses if multiple people wrote the message. | ``getFrom()`` / ``setFrom()`` |
++-------------------------------+------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------+
+| ``Sender`` | Specifies the address of the person who physically sent the message (higher precedence than ``From:``) | ``getSender()`` / ``setSender()`` |
++-------------------------------+------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------+
+| ``To`` | Specifies the addresses of the intended recipients | ``getTo()`` / ``setTo()`` |
++-------------------------------+------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------+
+| ``Cc`` | Specifies the addresses of recipients who will be copied in on the message | ``getCc()`` / ``setCc()`` |
++-------------------------------+------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------+
+| ``Bcc`` | Specifies the addresses of recipients who the message will be blind-copied to. Other recipients will not be aware of these copies. | ``getBcc()`` / ``setBcc()`` |
++-------------------------------+------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------+
+| ``Reply-To`` | Specifies the address where replies are sent to | ``getReplyTo()`` / ``setReplyTo()`` |
++-------------------------------+------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------+
+| ``Subject`` | Specifies the subject line that is displayed in the recipients' mail client | ``getSubject()`` / ``setSubject()`` |
++-------------------------------+------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------+
+| ``Date`` | Specifies the date at which the message was sent | ``getDate()`` / ``setDate()`` |
++-------------------------------+------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------+
+| ``Content-Type`` | Specifies the format of the message (usually text/plain or text/html) | ``getContentType()`` / ``setContentType()`` |
++-------------------------------+------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------+
+| ``Content-Transfer-Encoding`` | Specifies the encoding scheme in the message | ``getEncoder()`` / ``setEncoder()`` |
++-------------------------------+------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------+
+
+Working with a Message Object
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Although there are a lot of available methods on a message object, you only
+need to make use of a small subset of them. Usually you'll use
+``setSubject()``, ``setTo()`` and
+``setFrom()`` before setting the body of your message with
+``setBody()``.
+
+Calling methods is simple. You just call them like functions, but using the
+object operator "``<![CDATA[->]]>``" to do so. If you've created
+a message object and called it ``$message`` then you'd set a
+subject on it like so:
+
+.. code-block:: php
+
+ require_once 'lib/swift_required.php';
+
+ $message = Swift_Message::newInstance();
+ $message->setSubject('My subject');
+
+All MIME entities (including a message) have a ``toString()``
+method that you can call if you want to take a look at what is going to be
+sent. For example, if you ``<![CDATA[echo
+$message->toString();]]>`` you would see something like this:
+
+.. code-block:: bash
+
+ Message-ID: <1230173678.4952f5eeb1432@swift.generated>
+ Date: Thu, 25 Dec 2008 13:54:38 +1100
+ Subject: Example subject
+ From: Chris Corbyn <chris@w3style.co.uk>
+ To: Receiver Name <recipient@example.org>
+ MIME-Version: 1.0
+ Content-Type: text/plain; charset=utf-8
+ Content-Transfer-Encoding: quoted-printable
+
+ Here is the message
+
+We'll take a closer look at the methods you use to create your message in the
+following sections.
+
+Adding Content to Your Message
+------------------------------
+
+Rich content can be added to messages in Swift Mailer with relative ease by
+calling methods such as setSubject(), setBody(), addPart() and attach().
+
+Setting the Subject Line
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+The subject line, displayed in the recipients' mail client can be set with the
+setSubject() method, or as a parameter to Swift_Message::newInstance().
+
+To set the subject of your Message:
+
+* Call the ``setSubject()`` method of the Message, or specify it at the time
+ you create the message.
+
+ .. code-block:: php
+
+ // Pass it as a parameter when you create the message
+ $message = Swift_Message::newInstance('My amazing subject');
+
+ // Or set it after like this
+ $message->setSubject('My amazing subject');
+
+Setting the Body Content
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+The body of the message -- seen when the user opens the message --
+is specified by calling the setBody() method. If an alternative body is to be
+included addPart() can be used.
+
+The body of a message is the main part that is read by the user. Often people
+want to send a message in HTML format (``text/html``), other
+times people want to send in plain text (``text/plain``), or
+sometimes people want to send both versions and allow the recipient to chose
+how they view the message.
+
+As a rule of thumb, if you're going to send a HTML email, always include a
+plain-text equivalent of the same content so that users who prefer to read
+plain text can do so.
+
+To set the body of your Message:
+
+* Call the ``setBody()`` method of the Message, or specify it at the time you
+ create the message.
+
+* Add any alternative bodies with ``addPart()``.
+
+If the recipient's mail client offers preferences for displaying text vs. HTML then
+the mail client will present that part to the user where available. In other cases
+the mail client will display the "best" part it can - usually HTML if you've included
+HTML.
+
+.. code-block:: php
+
+ //Pass it as a parameter when you create the message
+ $message = Swift_Message::newInstance('Subject here', 'My amazing body');
+
+ //Or set it after like this
+ $message->setBody('My <em>amazing</em> body', 'text/html');
+
+ //Add alternative parts with addPart()
+ $message->addPart('My amazing body in plain text', 'text/plain');
+
+Attaching Files
+---------------
+
+Attachments are downloadable parts of a message and can be added by calling
+the attach() method on the message. You can add attachments that exist on
+disk, or you can create attachments on-the-fly.
+
+Attachments are actually an interesting area of Swift Mailer and something
+that could put a lot of power at your fingertips if you grasp the concept
+behind the way a message is held together.
+
+Although we refer to files sent over e-mails as "attachments" -- because
+they're attached to the message -- lots of other parts of the message are
+actually "attached" even if we don't refer to these parts as attachments.
+
+File attachments are created by the ``Swift_Attachment`` class
+and then attached to the message via the ``attach()`` method on
+it. For all of the "every day" MIME types such as all image formats, word
+documents, PDFs and spreadsheets you don't need to explicitly set the
+content-type of the attachment, though it would do no harm to do so. For less
+common formats you should set the content-type -- which we'll cover in a
+moment.
+
+Attaching Existing Files
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Files that already exist, either on disk or at a URL can be attached to a
+message with just one line of code, using Swift_Attachment::fromPath().
+
+You can attach files that exist locally, or if your PHP installation has
+``allow_url_fopen`` turned on you can attach files from other
+websites.
+
+To attach an existing file:
+
+* Create an attachment with ``Swift_Attachment::fromPath()``.
+
+* Add the attachment to the message with ``attach()``.
+
+The attachment will be presented to the recipient as a downloadable file with
+the same filename as the one you attached.
+
+.. code-block:: php
+
+ //Create the attachment
+ // * Note that you can technically leave the content-type parameter out
+ $attachment = Swift_Attachment::fromPath('/path/to/image.jpg', 'image/jpeg');
+
+ //Attach it to the message
+ $message->attach($attachment);
+
+
+ //The two statements above could be written in one line instead
+ $message->attach(Swift_Attachment::fromPath('/path/to/image.jpg'));
+
+
+ //You can attach files from a URL if allow_url_fopen is on in php.ini
+ $message->attach(Swift_Attachment::fromPath('http://site.tld/logo.png'));
+
+Setting the Filename
+~~~~~~~~~~~~~~~~~~~~
+
+Usually you don't need to explicitly set the filename of an attachment because
+the name of the attached file will be used by default, but if you want to set
+the filename you use the setFilename() method of the Attachment.
+
+To change the filename of an attachment:
+
+* Call its ``setFilename()`` method.
+
+The attachment will be attached in the normal way, but meta-data sent inside
+the email will rename the file to something else.
+
+.. code-block:: php
+
+ //Create the attachment and call its setFilename() method
+ $attachment = Swift_Attachment::fromPath('/path/to/image.jpg')
+ ->setFilename('cool.jpg');
+
+
+ //Because there's a fluid interface, you can do this in one statement
+ $message->attach(
+ Swift_Attachment::fromPath('/path/to/image.jpg')->setFilename('cool.jpg')
+ );
+
+Attaching Dynamic Content
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Files that are generated at runtime, such as PDF documents or images created
+via GD can be attached directly to a message without writing them out to disk.
+Use the standard Swift_Attachment::newInstance() method.
+
+To attach dynamically created content:
+
+* Create your content as you normally would.
+
+* Create an attachment with ``Swift_Attachment::newInstance()``, specifying
+ the source data of your content along with a name and the content-type.
+
+* Add the attachment to the message with ``attach()``.
+
+The attachment will be presented to the recipient as a downloadable file
+with the filename and content-type you specify.
+
+.. note::
+
+ If you would usually write the file to disk anyway you should just attach
+ it with ``Swift_Attachment::fromPath()`` since this will use less memory:
+
+ .. code-block: php
+
+ //Create your file contents in the normal way, but don't write them to disk
+ $data = create_my_pdf_data();
+
+ //Create the attachment with your data
+ $attachment = Swift_Attachment::newInstance($data, 'my-file.pdf', 'application/pdf');
+
+ //Attach it to the message
+ $message->attach($attachment);
+
+
+ //You can alternatively use method chaining to build the attachment
+ $attachment = Swift_Attachment::newInstance()
+ ->setFilename('my-file.pdf')
+ ->setContentType('application/pdf')
+ ->setBody($data)
+ ;
+
+Changing the Disposition
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Attachments just appear as files that can be saved to the Desktop if desired.
+You can make attachment appear inline where possible by using the
+setDisposition() method of an attachment.
+
+To make an attachment appear inline:
+
+* Call its ``setDisposition()`` method.
+
+The attachment will be displayed within the email viewing window if the mail
+client knows how to display it.
+
+.. note::
+
+ If you try to create an inline attachment for a non-displayable file type
+ such as a ZIP file, the mail client should just present the attachment as
+ normal:
+
+ .. code-block:: php
+
+ //Create the attachment and call its setDisposition() method
+ $attachment = Swift_Attachment::fromPath('/path/to/image.jpg')
+ ->setDisposition('inline');
+
+
+ //Because there's a fluid interface, you can do this in one statement
+ $message->attach(
+ Swift_Attachment::fromPath('/path/to/image.jpg')->setDisposition('inline')
+ );
+
+Embedding Inline Media Files
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Often people want to include an image or other content inline with a HTML
+message. It's easy to do this with HTML linking to remote resources, but this
+approach is usually blocked by mail clients. Swift Mailer allows you to embed
+your media directly into the message.
+
+Mail clients usually block downloads from remote resources because this
+technique was often abused as a mean of tracking who opened an email. If
+you're sending a HTML email and you want to include an image in the message
+another approach you can take is to embed the image directly.
+
+Swift Mailer makes embedding files into messages extremely streamlined. You
+embed a file by calling the ``embed()`` method of the message,
+which returns a value you can use in a ``src`` or
+``href`` attribute in your HTML.
+
+Just like with attachments, it's possible to embed dynamically generated
+content without having an existing file available.
+
+The embedded files are sent in the email as a special type of attachment that
+has a unique ID used to reference them within your HTML attributes. On mail
+clients that do not support embedded files they may appear as attachments.
+
+Although this is commonly done for images, in theory it will work for any
+displayable (or playable) media type. Support for other media types (such as
+video) is dependent on the mail client however.
+
+Embedding Existing Files
+........................
+
+Files that already exist, either on disk or at a URL can be embedded in a
+message with just one line of code, using Swift_EmbeddedFile::fromPath().
+
+You can embed files that exist locally, or if your PHP installation has
+``allow_url_fopen`` turned on you can embed files from other
+websites.
+
+To embed an existing file:
+
+* Create a message object with ``Swift_Message::newInstance()``.
+
+* Set the body as HTML, and embed a file at the correct point in the message with ``embed()``.
+
+The file will be displayed with the message inline with the HTML wherever its ID
+is used as a ``src`` attribute.
+
+.. note::
+
+ ``Swift_Image`` and ``Swift_EmbeddedFile`` are just aliases of one
+ another. ``Swift_Image`` exists for semantic purposes.
+
+.. note::
+
+ You can embed files in two stages if you prefer. Just capture the return
+ value of ``embed()`` in a variable and use that as the ``src`` attribute.
+
+ .. code-block: php
+
+ //Create the message
+ $message = Swift_Message::newInstance('My subject');
+
+ //Set the body
+ $message->setBody(
+ '<html>' .
+ ' <head></head>' .
+ ' <body>' .
+ ' Here is an image <img src="' . //Embed the file
+ $message->embed(Swift_Image::fromPath('image.png')) .
+ '" alt="Image" />' .
+ ' Rest of message' .
+ ' </body>' .
+ '</html>',
+ 'text/html' //Mark the content-type as HTML
+ );
+
+ //You can embed files from a URL if allow_url_fopen is on in php.ini
+ $message->setBody(
+ '<html>' .
+ ' <head></head>' .
+ ' <body>' .
+ ' Here is an image <img src="' .
+ $message->embed(Swift_Image::fromPath('http://site.tld/logo.png')) .
+ '" alt="Image" />' .
+ ' Rest of message' .
+ ' </body>' .
+ '</html>',
+ 'text/html'
+ );
+
+
+ // If placing the embed() code inline becomes cumbersome
+ // it's easy to do this in two steps
+ $cid = $message->embed(Swift_Image::fromPath('image.png'));
+
+ $message->setBody(
+ '<html>' .
+ ' <head></head>' .
+ ' <body>' .
+ ' Here is an image <img src="' . $cid . '" alt="Image" />' .
+ ' Rest of message' .
+ ' </body>' .
+ '</html>',
+ 'text/html' //Mark the content-type as HTML
+ );
+
+Embedding Dynamic Content
+.........................
+
+Images that are generated at runtime, such as images created via GD can be
+embedded directly to a message without writing them out to disk. Use the
+standard Swift_Image::newInstance() method.
+
+To embed dynamically created content:
+
+* Create a message object with ``Swift_Message::newInstance()``.
+
+* Set the body as HTML, and embed a file at the correct point in the message
+ with ``embed()``. You will need to specify a filename and a content-type.
+
+The file will be displayed with the message inline with the HTML wherever its ID
+is used as a ``src`` attribute.
+
+.. note::
+
+ ``Swift_Image`` and ``Swift_EmbeddedFile`` are just aliases of one
+ another. ``Swift_Image`` exists for semantic purposes.
+
+.. note::
+
+ You can embed files in two stages if you prefer. Just capture the return
+ value of ``embed()`` in a variable and use that as the ``src`` attribute.
+
+ .. code-block:: php
+
+ //Create your file contents in the normal way, but don't write them to disk
+ $img_data = create_my_image_data();
+
+ //Create the message
+ $message = Swift_Message::newInstance('My subject');
+
+ //Set the body
+ $message->setBody(
+ '<html>' .
+ ' <head></head>' .
+ ' <body>' .
+ ' Here is an image <img src="' . //Embed the file
+ $message->embed(Swift_Image::newInstance($img_data, 'image.jpg', 'image/jpeg')) .
+ '" alt="Image" />' .
+ ' Rest of message' .
+ ' </body>' .
+ '</html>',
+ 'text/html' //Mark the content-type as HTML
+ );
+
+
+ // If placing the embed() code inline becomes cumbersome
+ // it's easy to do this in two steps
+ $cid = $message->embed(Swift_Image::newInstance($img_data, 'image.jpg', 'image/jpeg'));
+
+ $message->setBody(
+ '<html>' .
+ ' <head></head>' .
+ ' <body>' .
+ ' Here is an image <img src="' . $cid . '" alt="Image" />' .
+ ' Rest of message' .
+ ' </body>' .
+ '</html>',
+ 'text/html' //Mark the content-type as HTML
+ );
+
+Adding Recipients to Your Message
+---------------------------------
+
+Recipients are specified within the message itself via setTo(), setCc() and
+setBcc(). Swift Mailer reads these recipients from the message when it gets
+sent so that it knows where to send the message to.
+
+Message recipients are one of three types:
+
+* ``To:`` recipients -- the primary recipients (required)
+
+* ``Cc:`` recipients -- receive a copy of the message (optional)
+
+* ``Bcc:`` recipients -- hidden from other recipients (optional)
+
+Each type can contain one, or several addresses. It's possible to list only
+the addresses of the recipients, or you can personalize the address by
+providing the real name of the recipient.
+
+.. sidebar:: Syntax for Addresses
+
+ If you only wish to refer to a single email address (for example your ``From:``
+ address) then you can just use a string.
+
+ .. code-block:: php
+
+ $message->setFrom('some@address.tld');
+
+ If you want to include a name then you must use an associative array.
+
+ .. code-block:: php
+
+ $message->setFrom(array('some@address.tld' => 'The Name'));
+
+ If you want to include multiple addresses then you must use an array.
+
+ .. code-block:: php
+
+ $message->setTo(array('some@address.tld', 'other@address.tld'));
+
+ You can mix personalized (addresses with a name) and non-personalized
+ addresses in the same list by mixing the use of associative and non-associative
+ array syntax.
+
+ .. code-block:: php
+
+ $message->setTo(array(
+ 'recipient-with-name@example.org' => 'Recipient Name One',
+ 'no-name@example.org', //Note that this is not a key-value pair
+ 'named-recipient@example.org' => 'Recipient Name Two'
+ ));
+
+Setting ``To:`` Recipients
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``To:`` recipients are required in a message and are set with the
+``setTo()`` or ``addTo()`` methods of the message.
+
+To set ``To:`` recipients, create the message object using either
+``new Swift_Message( ... )`` or
+``Swift_Message::newInstance( ... )``, then call the
+``setTo()`` method with a complete array of addresses, or use the
+``addTo()`` method to iteratively add recipients.
+
+The ``setTo()`` method accepts input in various formats as described earlier in
+this chapter. The ``addTo()`` method takes either one or two parameters. The
+first being the email address and the second optional parameter being the name
+of the recipient.
+
+``To:`` recipients are visible in the message headers and will be
+seen by the other recipients.
+
+.. note::
+
+ Multiple calls to ``setTo()`` will not add new recipients -- each
+ call overrides the previous calls. If you want to iteratively add
+ recipients, use the ``addTo()`` method.
+
+ .. code-block:: php
+
+ //Using setTo() to set all recipients in one go
+ $message->setTo(array(
+ 'person1@example.org',
+ 'person2@otherdomain.org' => 'Person 2 Name',
+ 'person3@example.org',
+ 'person4@example.org',
+ 'person5@example.org' => 'Person 5 Name'
+ ));
+
+ //Using addTo() to add recipients iteratively
+ $message->addTo('person1@example.org');
+ $message->addTo('person2@example.org', 'Person 2 Name');
+
+Setting ``Cc:`` Recipients
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``Cc:`` recipients are set with the
+``setCc()`` or ``addCc()`` methods of the message.
+
+To set ``Cc:`` recipients, create the message object using either
+``new Swift_Message( ... )`` or
+``Swift_Message::newInstance( ... )``, then call the
+``setCc()`` method with a complete array of addresses, or use the
+``addCc()`` method to iteratively add recipients.
+
+The ``setCc()`` method accepts input in various formats as described earlier in
+this chapter. The ``addCc()`` method takes either one or two parameters. The
+first being the email address and the second optional parameter being the name
+of the recipient.
+
+``Cc:`` recipients are visible in the message headers and will be
+seen by the other recipients.
+
+.. note::
+
+ Multiple calls to ``setCc()`` will not add new recipients -- each
+ call overrides the previous calls. If you want to iteratively add Cc:
+ recipients, use the ``addCc()`` method.
+
+ .. code-block:: php
+
+ //Using setCc() to set all recipients in one go
+ $message->setCc(array(
+ 'person1@example.org',
+ 'person2@otherdomain.org' => 'Person 2 Name',
+ 'person3@example.org',
+ 'person4@example.org',
+ 'person5@example.org' => 'Person 5 Name'
+ ));
+
+ //Using addCc() to add recipients iteratively
+ $message->addCc('person1@example.org');
+ $message->addCc('person2@example.org', 'Person 2 Name');
+
+Setting ``Bcc:`` Recipients
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``Bcc:`` recipients receive a copy of the message without anybody
+else knowing it, and are set with the ``setBcc()`` or
+``addBcc`` methods of the message.
+
+To set ``Bcc:`` recipients, create the message object using
+either ``new Swift_Message( ... )`` or
+``Swift_Message::newInstance( ... )``, then call the
+``setBcc()`` method with a complete array of addresses, or use
+the ``addBcc()`` method to iteratively add recipients.
+
+The ``setBcc()`` method accepts input in various formats as described earlier in
+this chapter. The ``addBcc()`` method takes either one or two parameters. The
+first being the email address and the second optional parameter being the name
+of the recipient.
+
+Only the individual ``Bcc:`` recipient will see their address in
+the message headers. Other recipients (including other ``Bcc:``
+recipients) will not see the address.
+
+.. note::
+
+ Multiple calls to ``setBcc()`` will not add new recipients -- each
+ call overrides the previous calls. If you want to iteratively add Bcc:
+ recipients, use the ``addBcc()`` method.
+
+ .. code-block:: php
+
+ //Using setBcc() to set all recipients in one go
+ $message->setBcc(array(
+ 'person1@example.org',
+ 'person2@otherdomain.org' => 'Person 2 Name',
+ 'person3@example.org',
+ 'person4@example.org',
+ 'person5@example.org' => 'Person 5 Name'
+ ));
+
+ //Using addBcc() to add recipients iteratively
+ $message->addBcc('person1@example.org');
+ $message->addBcc('person2@example.org', 'Person 2 Name');
+
+Specifying Sender Details
+-------------------------
+
+An email must include information about who sent it. Usually this is managed
+by the ``From:`` address, however there are other options.
+
+The sender information is contained in three possible places:
+
+* ``From:`` -- the address(es) of who wrote the message (required)
+
+* ``Sender:`` -- the address of the single person who sent the message
+ (optional)
+
+* ``Return-Path:`` -- the address where bounces should go to (optional)
+
+You must always include a ``From:`` address by using
+``setFrom()`` on the message. Swift Mailer will use this as the
+default ``Return-Path:`` unless otherwise specified.
+
+The ``Sender:`` address exists because the person who actually
+sent the email may not be the person who wrote the email. It has a higher
+precedence than the ``From:`` address and will be used as the
+``Return-Path:`` unless otherwise specified.
+
+Setting the ``From:`` Address
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A ``From:`` address is required and is set with the
+``setFrom()`` method of the message.
+
+``From:`` addresses specify who actually wrote the email, and
+usually who sent it.
+
+What most people probably don't realise is that you can have more than one
+``From:`` address if more than one person wrote the email --
+for example if an email was put together by a committee.
+
+To set the ``From:`` address(es):
+
+* Call the ``setFrom()`` method on the Message.
+
+The ``From:`` address(es) are visible in the message headers and
+will be seen by the recipients.
+
+.. note::
+
+ If you set multiple ``From:`` addresses then you absolutely must set a
+ ``Sender:`` address to indicate who physically sent the message.
+
+ .. code-block:: php
+
+ //Set a single From: address
+ $message->setFrom('your@address.tld');
+
+ //Set a From: address including a name
+ $message->setFrom(array('your@address.tld' => 'Your Name'));
+
+ //Set multiple From: addresses if multiple people wrote the email
+ $message->setFrom(array(
+ 'person1@example.org' => 'Sender One',
+ 'person2@example.org' => 'Sender Two'
+ ));
+
+Setting the ``Sender:`` Address
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A ``Sender:`` address specifies who sent the message and is set
+with the ``setSender()`` method of the message.
+
+To set the ``Sender:`` address:
+
+* Call the ``setSender()`` method on the Message.
+
+The ``Sender:`` address is visible in the message headers and
+will be seen by the recipients.
+
+This address will be used as the ``Return-Path:`` unless
+otherwise specified.
+
+.. note::
+
+ If you set multiple ``From:`` addresses then you absolutely must set a
+ ``Sender:`` address to indicate who physically sent the message.
+
+You must not set more than one sender address on a message because it's not
+possible for more than one person to send a single message.
+
+.. code-block:: php
+
+ $message->setSender('your@address.tld');
+
+Setting the ``Return-Path:`` (Bounce) Address
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``Return-Path:`` address specifies where bounce notifications should
+be sent and is set with the ``setReturnPath()`` method of the message.
+
+You can only have one ``Return-Path:`` and it must not include
+a personal name.
+
+To set the ``Return-Path:`` address:
+
+* Call the ``setReturnPath()`` method on the Message.
+
+Bouce notifications will be sent to this address.
+
+.. code-block:: php
+
+ $message->setReturnPath('bounces@address.tld');
+
+Requesting a Read Receipt
+-------------------------
+
+It is possible to request a read-receipt to be sent to an address when the
+email is opened. To request a read receipt set the address with
+``setReadReceiptTo()``.
+
+To request a read receipt:
+
+* Set the address you want the receipt to be sent to with the
+ ``setReadReceiptTo()`` method on the Message.
+
+When the email is opened, if the mail client supports it a notification will be sent to this address.
+
+.. note::
+
+ Read receipts won't work for the majority of recipients since many mail
+ clients auto-disable them. Those clients that will send a read receipt
+ will make the user aware that one has been requested.
+
+ .. code-block:: php
+
+ $message->setReadReceiptTo('your@address.tld');
+
+Setting the Character Set
+-------------------------
+
+The character set of the message (and it's MIME parts) is set with the
+setCharset() method. You can also change the global default of UTF-8 by
+working with the Swift_Preferences class.
+
+Swift Mailer will default to the UTF-8 character set unless otherwise
+overridden. UTF-8 will work in most instances since it includes all of the
+standard US keyboard characters in addition to most international characters.
+
+It is absolutely vital however that you know what character set your message
+(or it's MIME parts) are written in otherwise your message may be received
+completely garbled.
+
+There are two places in Swift Mailer where you can change the character set:
+
+* In the Swift_Preferences class
+
+* On each individual message and/or MIME part
+
+To set the character set of your Message:
+
+* Change the global UTF-8 setting by calling
+ ``Swift_Preferences::setCharset()``; or
+
+* Call the ``setCharset()`` method on the message or the MIME part.
+
+ .. code-block:: php
+
+ //Approach 1: Change the global setting (suggested)
+ Swift_Preferences::getInstance()->setCharset('iso-8859-2');
+
+ //Approach 2: Call the setCharset() method of the message
+ $message = Swift_Message::newInstance()
+ ->setCharset('iso-8859-2');
+
+ //Apprach 3: Specify the charset when setting the body
+ $message->setBody('My body', 'text/html', 'iso-8859-2');
+
+ //Approach 4: Specify the charset for each part added
+ $message->addPart('My part', 'text/plain', 'iso-8859-2');
+
+Setting the Line Length
+-----------------------
+
+The length of lines in a message can be changed by using the
+``setMaxLineLength()`` method on the message. It should be kept
+to less than 1000 characters.
+
+Swift Mailer defaults to using 78 characters per line in a message. This is
+done for historical reasons and so that the message can be easily viewed in
+plain-text terminals.
+
+To change the maximum length of lines in your Message:
+
+* Call the ``setMaxLineLength()`` method on the Message.
+
+Lines that are longer than the line length specified will be wrapped between
+words.
+
+.. note::
+
+ You should never set a maximum length longer than 1000 characters
+ according to RFC 2822. Doing so could have unspecified side-effects such
+ as truncating parts of your message when it is transported between SMTP
+ servers.
+
+ .. code-block:: php
+
+ $message->setMaxLineLength(1000);
+
+Setting the Message Priority
+----------------------------
+
+You can change the priority of the message with
+``setPriority()``. Setting the priority will not change the way
+your email is sent -- it is purely an indicative setting for the
+recipient.
+
+The priority of a message is an indication to the recipient what significance
+it has. Swift Mailer allows you to set the priority by calling the
+``setPriority`` method. This method takes an integer value
+between 1 and 5:
+
+* Highest
+* High
+* Normal
+* Low
+* Lowest
+
+To set the message priority:
+
+* Set the priority as an integer between 1 and 5 with the ``setPriority()``
+ method on the Message.
+
+.. code-block:: php
+
+ //Indicate "High" priority
+ $message->setPriority(2);
View
390 docs/book/en/07-Message-Headers.markdown → doc/07-Message-Headers.rst
@@ -8,28 +8,29 @@ this.
Header Basics
-------------
-All MIME entities in Swift Mailer &#8211; including the message itself &#8211;
+All MIME entities in Swift Mailer -- including the message itself --
store their headers in a single object called a HeaderSet. This HeaderSet is
-retrieved with the `getHeaders()` method.
+retrieved with the ``getHeaders()`` method.
As mentioned in the previous chapter, everything that forms a part of a
message in Swift Mailer is a MIME entity that is represented by an instance of
-`Swift_Mime_MimeEntity`. This includes &#8211; most notably &#8211; the
+``Swift_Mime_MimeEntity``. This includes -- most notably -- the
message object itself, attachments, MIME parts and embedded images. Each of
these MIME entities consists of a body and a set of headers that describe the
body.
For all of the "standard" headers in these MIME entities, such as the
-`Content-Type`, there are named methods for working with them,
-such as `setContentType()` and
-`getContentType()`. This is because headers are a moderately
+``Content-Type``, there are named methods for working with them,
+such as ``setContentType()`` and
+``getContentType()``. This is because headers are a moderately
complex area of the library. Each header has a slightly different required
structure that it must meet in order to comply with the standards that govern
email (and that are checked by spam blockers etc).
You fetch the HeaderSet from a MIME entity like so:
- [php]
+.. code-block:: php
+
$message = Swift_Message::newInstance();
//Fetch the HeaderSet from a Message object
@@ -48,7 +49,8 @@ set of headers to those in a message.
You can find out what the HeaderSet contains with a quick loop, dumping out
the names of the headers:
- [php]
+.. code-block:: php
+
foreach ($headers->getAll() as $header) {
printf("%s<br />\n", $header->getFieldName());
}
@@ -65,9 +67,10 @@ the names of the headers:
*/
You can also dump out the rendered HeaderSet by calling its
-`toString()` method:
+``toString()`` method:
+
+.. code-block:: php
- [php]
echo $headers->toString();
/*
@@ -84,20 +87,21 @@ You can also dump out the rendered HeaderSet by calling its
Where the complexity comes in is when you want to modify an existing header.
This complexity comes from the fact that each header can be of a slightly
different type (such as a Date header, or a header that contains email
-addresses, or a header that has key-value parameters on it&#8230;). Each
-header in the HeaderSet is an instance of `Swift_Mime_Header`.
+addresses, or a header that has key-value parameters on it!). Each
+header in the HeaderSet is an instance of ``Swift_Mime_Header``.
They all have common functionality, but knowing exactly what type of header
you're working with will allow you a little more control.
You can determine the type of header by comparing the return value of its
-`getFieldType()` method with the constants
-`TYPE_TEXT`, `TYPE_PARAMETERIZED`,
-`TYPE_DATE`, `TYPE_MAILBOX`,
-`TYPE_ID` and `TYPE_PATH` which are defined in
-`Swift_Mime_Header`.
+``getFieldType()`` method with the constants
+``TYPE_TEXT``, ``TYPE_PARAMETERIZED``,
+``TYPE_DATE``, ``TYPE_MAILBOX``,
+``TYPE_ID`` and ``TYPE_PATH`` which are defined in
+``Swift_Mime_Header``.
- [php]
+.. code-block:: php
+
foreach ($headers->getAll() as $header) {
switch ($header->getFieldType()) {
case Swift_Mime_Header::TYPE_TEXT: $type = 'text';
@@ -131,21 +135,22 @@ Headers can be removed from the set, modified within the set, or added to the
set.
The following sections show you how to work with the HeaderSet and explain the
-details of each implementation of `Swift_Mime_Header` that may
+details of each implementation of ``Swift_Mime_Header`` that may
exist within the HeaderSet.
Header Types
------------
Because all headers are modeled on different data (dates, addresses,
-text&#8230;) there are different types of Header in Swift Mailer. Swift Mailer
+text!) there are different types of Header in Swift Mailer. Swift Mailer
attempts to categorize all possible MIME headers into more general groups,
defined by a small number of classes.
-### Text Headers
+Text Headers
+~~~~~~~~~~~~
Text headers are the simplest type of Header. They contain textual information
-with no special information included within it &#8211; for example the Subject
+with no special information included within it -- for example the Subject
header in a message.
There's nothing particularly interesting about a text header, though it is
@@ -155,14 +160,15 @@ contains characters that are not permitted in a message header (such as new
lines, or non-ascii characters) then the header takes care of encoding the
text so that it can be used.
-No header &#8211; including text headers &#8211; in Swift Mailer is vulnerable
+No header -- including text headers -- in Swift Mailer is vulnerable
to header-injection attacks. Swift Mailer breaks any attempt at header
injection by encoding the dangerous data into a non-dangerous form.
It's easy to add a new text header to a HeaderSet. You do this by calling the
-HeaderSet's `addTextHeader()` method.
+HeaderSet's ``addTextHeader()`` method.
+
+.. code-block:: php
- [php]
$message = Swift_Message::newInstance();
$headers = $message->getHeaders();
@@ -170,17 +176,19 @@ HeaderSet's `addTextHeader()` method.
$headers->addTextHeader('Your-Header-Name', 'the header value');
Changing the value of an existing text header is done by calling it's
-`setValue()` method.
+``setValue()`` method.
+
+.. code-block:: php
- [php]
$subject = $message->getHeaders()->getHeader('Subject');
$subject->setValue('new subject');
-When output via `toString()`, a text header produces something
+When output via ``toString()``, a text header produces something
like the following:
- [php]
+.. code-block:: php
+
$subject = $message->getHeaders()->getHeader('Subject');
$subject->setValue('amazing subject line');
@@ -197,7 +205,8 @@ If the header contains any characters that are outside of the US-ASCII range
however, they will be encoded. This is nothing to be concerned about since
mail clients will decode them back.
- [php]
+.. code-block:: php
+
$subject = $message->getHeaders()->getHeader('Subject');
$subject->setValue('contains – dash');
@@ -210,7 +219,8 @@ mail clients will decode them back.
*/
-### Parameterized Headers
+Parameterized Headers
+~~~~~~~~~~~~~~~~~~~~~
Parameterized headers are text headers that contain key-value parameters
following the textual content. The Content-Type header of a message is a
@@ -223,11 +233,12 @@ methods from text headers are available in addition to the methods described
here.
Adding a parameterized header to a HeaderSet is done by using the
-`addParameterizedHeader()` method which takes a text value like
-`addTextHeader()` but it also accepts an associative array of
+``addParameterizedHeader()`` method which takes a text value like
+``addTextHeader()`` but it also accepts an associative array of
key-value parameters.
- [php]
+.. code-block:: php
+
$message = Swift_Message::newInstance();
$headers = $message->getHeaders();
@@ -237,14 +248,15 @@ key-value parameters.
array('foo' => 'bar')
);
-To change the text value of the header, call it's `setValue()`
+To change the text value of the header, call it's ``setValue()``
method just as you do with text headers.
To change the parameters in the header, call the header's
-`setParameters()` method or the `setParameter()`
+``setParameters()`` method or the ``setParameter()``
method (note the pluralization).
- [php]
+.. code-block:: php
+
$type = $message->getHeaders()->getHeader('Content-Type');
//setParameters() takes an associative array
@@ -256,10 +268,11 @@ method (note the pluralization).
//setParameter() takes two args for $key and $value
$type->setParameter('charset', 'iso-8859-1');
-When output via `toString()`, a parameterized header produces
+When output via ``toString()``, a parameterized header produces
something like the following:
- [php]
+.. code-block:: php
+
$type = $message->getHeaders()->getHeader('Content-Type');
$type->setValue('text/html');
@@ -279,7 +292,8 @@ nothing to be concerned about since mail clients will decode them back.
Likewise, if the parameters contain any non-ascii characters they will be
encoded so that they can be transmitted safely.
- [php]
+.. code-block:: php
+
$attachment = Swift_Attachment::newInstance();
$disp = $attachment->getHeaders()->getHeader('Content-Disposition');
@@ -295,24 +309,26 @@ encoded so that they can be transmitted safely.
*/
-### Date Headers
+Date Headers
+~~~~~~~~~~~~
Date headers contains an RFC 2822 formatted date (i.e. what PHP's
-`date('r')` returns). They are used anywhere a date or time is
+``date('r')`` returns). They are used anywhere a date or time is
needed to be presented as a message header.
The data on which a date header is modeled is simply a UNIX timestamp such as that
-returned by `time()` or `strtotime()`. The timestamp
+returned by ``time()`` or ``strtotime()``. The timestamp
is used to create a correctly structured RFC 2822 formatted date such as
-`Tue, 17 Feb 2009 22:26:31 +1100`.
+``Tue, 17 Feb 2009 22:26:31 +1100``.
-The obvious place this header type is used is in the `Date:` header
+The obvious place this header type is used is in the ``Date:`` header
of the message itself.
It's easy to add a new date header to a HeaderSet. You do this by calling
-the HeaderSet's `addDateHeader()` method.
+the HeaderSet's ``addDateHeader()`` method.
+
+.. code-block:: php
- [php]
$message = Swift_Message::newInstance();
$headers = $message->getHeaders();
@@ -320,17 +336,19 @@ the HeaderSet's `addDateHeader()` method.
$headers->addDateHeader('Your-Header-Name', strtotime('3 days ago'));
Changing the value of an existing date header is done by calling it's
-`setTimestamp()` method.
+``setTimestamp()`` method.
+
+.. code-block:: php
- [php]
$date = $message->getHeaders()->getHeader('Date');
$date->setTimestamp(time());
-When output via `toString()`, a date header produces something
+When output via ``toString()``, a date header produces something
like the following:
- [php]
+.. code-block:: php
+
$date = $message->getHeaders()->getHeader('Date');
echo $date->toString();
@@ -341,7 +359,8 @@ like the following:
*/
-### Mailbox (e-mail address) Headers
+Mailbox (e-mail address) Headers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Mailbox headers contain one or more email addresses, possibly with
personalized names attached to them. The data on which they are modeled is
@@ -351,15 +370,16 @@ Mailbox headers are probably the most complex header type to understand in
Swift Mailer because they accept their input as an array which can take
various forms, as described in the previous chapter.
-All of the headers that contain e-mail addresses in a message &#8211; with the
-exception of `Return-Path:` which has a stricter syntax &#8211;
-use this header type. That is, `To:`, `From:`
+All of the headers that contain e-mail addresses in a message -- with the
+exception of ``Return-Path:`` which has a stricter syntax --
+use this header type. That is, ``To:``, ``From:``
etc.
You add a new mailbox header to a HeaderSet by calling the HeaderSet's
-`addMailboxHeader()` method.
+``addMailboxHeader()`` method.
+
+.. code-block:: php
- [php]
$message = Swift_Message::newInstance();
$headers = $message->getHeaders();
@@ -372,9 +392,10 @@ You add a new mailbox header to a HeaderSet by calling the HeaderSet's
));
Changing the value of an existing mailbox header is done by calling it's
-`setNameAddresses()` method.
+``setNameAddresses()`` method.
+
+.. code-block:: php
- [php]
$to = $message->getHeaders()->getHeader('To');
$to->setNameAddresses(array(
@@ -384,11 +405,12 @@ Changing the value of an existing mailbox header is done by calling it's
));
If you don't wish to concern yourself with the complicated accepted input
-formats accepted by `setNameAddresses()` as described in the previous chapter
+formats accepted by ``setNameAddresses()`` as described in the previous chapter
and you only want to set one or more addresses (not names) then you can just
-use the `setAddresses()` method instead.
+use the ``setAddresses()`` method instead.
+
+.. code-block:: php
- [php]
$to = $message->getHeaders()->getHeader('To');
$to->setAddresses(array(
@@ -397,22 +419,25 @@ use the `setAddresses()` method instead.
'no-name@example.org'
));
->**NOTE**
->Both methods will accept the above input format in practice.
+.. note::
+
+ Both methods will accept the above input format in practice.
If all you want to do is set a single address in the header, you can use a
-string as the input parameter to `setAddresses()` and/or
-`setNameAddresses()`.
+string as the input parameter to ``setAddresses()`` and/or
+``setNameAddresses()``.
+
+.. code-block:: php
- [php]
$to = $message->getHeaders()->getHeader('To');
$to->setAddresses('joe-bloggs@example.org');
-When output via `toString()`, a mailbox header produces
+When output via ``toString()``, a mailbox header produces
something like the following:
- [php]
+.. code-block:: php
+
$to = $message->getHeaders()->getHeader('To');
$to->setNameAddresses(array(
@@ -430,26 +455,28 @@ something like the following:
*/
-### ID Headers
+ID Headers
+~~~~~~~~~~
ID headers contain identifiers for the entity (or the message). The most
notable ID header is the Message-ID header on the message itself.
An ID that exists inside an ID header looks more-or-less less like an email
-address. For example, `<![CDATA[<1234955437.499becad62ec2@example.org>]]>`.
+address. For example, ``<![CDATA[<1234955437.499becad62ec2@example.org>]]>``.
The part to the left of the @ sign is usually unique, based on the current time and
some random factor. The part on the right is usually a domain name.
-Any ID passed the an ID header's `setId()` method absolutely
+Any ID passed the an ID header's ``setId()`` method absolutely
MUST conform to this structure, otherwise you'll get an Exception thrown at you
-by Swift Mailer (a `Swift_RfcComplianceException`). This is to
+by Swift Mailer (a ``Swift_RfcComplianceException``). This is to
ensure that the generated email complies with relevant RFC documents and therefore
is less likely to be blocked as spam.
It's easy to add a new ID header to a HeaderSet. You do this by calling
-the HeaderSet's `addIdHeader()` method.
+the HeaderSet's ``addIdHeader()`` method.
+
+.. code-block:: php
- [php]
$message = Swift_Message::newInstance();
$headers = $message->getHeaders();
@@ -457,17 +484,19 @@ the HeaderSet's `addIdHeader()` method.
$headers->addIdHeader('Your-Header-Name', '123456.unqiue@example.org');
Changing the value of an existing date header is done by calling its
-`setId()` method.
+``setId()`` method.
+
+.. code-block:: php
- [php]
$msgId = $message->getHeaders()->getHeader('Message-ID');
$msgId->setId(time() . '.' . uniqid('thing') . '@example.org');
-When output via `toString()`, an ID header produces something
+When output via ``toString()``, an ID header produces something
like the following:
- [php]
+.. code-block:: php
+
$msgId = $message->getHeaders()->getHeader('Message-ID');
echo $msgId->toString();
@@ -478,16 +507,18 @@ like the following:
*/
-### Path Headers
+Path Headers
+~~~~~~~~~~~~
Path headers are like very-restricted mailbox headers. They contain a single
email address with no associated name. The Return-Path header of a message is
a path header.
You add a new path header to a HeaderSet by calling the HeaderSet's
-`addPathHeader()` method.
+``addPathHeader()`` method.
+
+.. code-block:: php
- [php]
$message = Swift_Message::newInstance();
$headers = $message->getHeaders();
@@ -496,17 +527,19 @@ You add a new path header to a HeaderSet by calling the HeaderSet's
Changing the value of an existing path header is done by calling its
-`setAddress()` method.
+``setAddress()`` method.
+
+.. code-block:: php
- [php]
$return = $message->getHeaders()->getHeader('Return-Path');
$return->setAddress('my-address@example.org');
-When output via `toString()`, a path header produces something
+When output via ``toString()``, a path header produces something
like the following:
- [php]
+.. code-block:: php
+
$return = $message->getHeaders()->getHeader('Return-Path');
$return->setAddress('person@example.org');
@@ -525,22 +558,24 @@ Header Operations
Working with the headers in a message involves knowing how to use the methods
on the HeaderSet and on the individual Headers within the HeaderSet.
-### Adding new Headers
+Adding new Headers
+~~~~~~~~~~~~~~~~~~
New headers can be added to the HeaderSet by using one of the provided
-`add..Header()` methods.
+``add..Header()`` methods.
To add a header to a MIME entity (such as the message):
-Get the HeaderSet from the entity by via its `getHeaders()`
+Get the HeaderSet from the entity by via its ``getHeaders()``
method.
- * Add the header to the HeaderSet by calling one of the `add..Header()`
- methods.
+* Add the header to the HeaderSet by calling one of the ``add..Header()``
+ methods.
The added header will appear in the message when it is sent.
- [php]
+.. code-block:: php
+
//Adding a custom header to a message
$message = Swift_Message::newInstance();
$headers = $message->getHeaders();
@@ -550,141 +585,152 @@ The added header will appear in the message when it is sent.
$attachment = Swift_Attachment::fromPath('/path/to/doc.pdf');
$attachment->getHeaders()->addDateHeader('X-Created-Time', time());
-### Retrieving Headers
+Retrieving Headers
+~~~~~~~~~~~~~~~~~~
-Headers are retrieved through the HeaderSet's `get()` and
-`getAll()` methods.
+Headers are retrieved through the HeaderSet's ``get()`` and
+``getAll()`` methods.
To get a header, or several headers from a MIME entity:
- * Get the HeaderSet from the entity by via its `getHeaders()` method.
+* Get the HeaderSet from the entity by via its ``getHeaders()`` method.
- * Get the header(s) from the HeaderSet by calling either `get()` or `getAll()`.
+* Get the header(s) from the HeaderSet by calling either ``get()`` or
+ ``getAll()``.
-When using `get()` a single header is returned that matches the
+When using ``get()`` a single header is returned that matches the
name (case insensitive) that is passed to it. When using
-`getAll()` with a header name, an array of headers with that
-name are returned. Calling `getAll()` with no arguments returns
+``getAll()`` with a header name, an array of headers with that
+name are returned. Calling ``getAll()`` with no arguments returns
an array of all headers present in the entity.
->**NOTE**
->It's valid for some headers to appear more than once in a message (e.g. the
->Received header). For this reason `getAll()` exists to fetch
->all headers with a specified name. In addition, `get()` accepts
->an optional numerical index, starting from zero to specify which header you
->want more specifically.
+.. note::
->**NOTE**
->If you want to modify the contents of the header and you don't know for sure
->what type of header it is then you may need to check the type by calling its
->`getFieldType()` method.
+ It's valid for some headers to appear more than once in a message (e.g.
+ the Received header). For this reason ``getAll()`` exists to fetch all
+ headers with a specified name. In addition, ``get()`` accepts an optional
+ numerical index, starting from zero to specify which header you want more
+ specifically.
- [php]
- $headers = $message->getHeaders();
+.. note::
+
+ If you want to modify the contents of the header and you don't know for
+ sure what type of header it is then you may need to check the type by
+ calling its ``getFieldType()`` method.
+
+ .. code-block:: php
- //Get the To: header
- $toHeader = $headers->get('To');
+ $headers = $message->getHeaders();
- //Get all headers named "X-Foo"
- $fooHeaders = $headers->getAll('X-Foo');
+ //Get the To: header
+ $toHeader = $headers->get('To');
- //Get the second header named "X-Foo"
- $foo = $headers->get('X-Foo', 1);
+ //Get all headers named "X-Foo"
+ $fooHeaders = $headers->getAll('X-Foo');
- //Get all headers that are present
- $all = $headers->getAll();
+ //Get the second header named "X-Foo"
+ $foo = $headers->get('X-Foo', 1);
-### Check if a Header Exists
+ //Get all headers that are present
+ $all = $headers->getAll();
+
+Check if a Header Exists
+~~~~~~~~~~~~~~~~~~~~~~~~
You can check if a named header is present in a HeaderSet by calling its
-`has()` method.
+``has()`` method.
To check if a header exists:
- * Get the HeaderSet from the entity by via its `getHeaders()` method.
+* Get the HeaderSet from the entity by via its ``getHeaders()`` method.
- * Call the HeaderSet's `has()` method specifying the header you're looking for.
+* Call the HeaderSet's ``has()`` method specifying the header you're looking
+ for.
-If the header exists, `true` will be returned or
-`false` if not.
+If the header exists, ``true`` will be returned or
+``false`` if not.
->**NOTE**
->It's valid for some headers to appear more than once in a message (e.g. the
->Received header). For this reason `has()` accepts an optional
->numerical index, starting from zero to specify which header you want to check
->more specifically.
+.. note::
- [php]
- $headers = $message->getHeaders();
+ It's valid for some headers to appear more than once in a message (e.g.
+ the Received header). For this reason ``has()`` accepts an optional
+ numerical index, starting from zero to specify which header you want to
+ check more specifically.
- //Check if the To: header exists
- if ($headers->has('To')) {
- echo 'To: exists';
- }
+ .. code-block:: php
- //Check if an X-Foo header exists twice (i.e. check for the 2nd one)
- if ($headers->has('X-Foo', 1)) {
- echo 'Second X-Foo header exists';
- }
+ $headers = $message->getHeaders();
+
+ //Check if the To: header exists
+ if ($headers->has('To')) {
+ echo 'To: exists';
+ }
-### Removing Headers
+ //Check if an X-Foo header exists twice (i.e. check for the 2nd one)
+ if ($headers->has('X-Foo', 1)) {
+ echo 'Second X-Foo header exists';
+ }
+
+Removing Headers
+~~~~~~~~~~~~~~~~
Removing a Header from the HeaderSet is done by calling the HeaderSet's
-`remove()` or `removeAll()` methods.
+``remove()`` or ``removeAll()`` methods.
To remove an existing header:
- * Get the HeaderSet from the entity by via its `getHeaders()`
- method.
+* Get the HeaderSet from the entity by via its ``getHeaders()`` method.
- * Call the HeaderSet's `remove()` or
- `removeAll()` methods specifying the header you want to
- remove.
+* Call the HeaderSet's ``remove()`` or ``removeAll()`` methods specifying the
+ header you want to remove.
-When calling `remove()` a single header will be removed. When
-calling `removeAll()` all headers with the given name will be
+When calling ``remove()`` a single header will be removed. When
+calling ``removeAll()`` all headers with the given name will be
removed. If no headers exist with the given name, no errors will occur.
->**NOTE**
->It's valid for some headers to appear more than once in a message (e.g. the
->Received header). For this reason `remove()` accepts an
->optional numerical index, starting from zero to specify which header you want
->to check more specifically. For the same reason, `removeAll()`
->exists to remove all headers that have the given name.
+.. note::
- [php]
- $headers = $message->getHeaders();
+ It's valid for some headers to appear more than once in a message (e.g.
+ the Received header). For this reason ``remove()`` accepts an optional
+ numerical index, starting from zero to specify which header you want to
+ check more specifically. For the same reason, ``removeAll()`` exists to
+ remove all headers that have the given name.
+
+ .. code-block:: php
- //Remove the Subject: header
- $headers->remove('Subject');
+ $headers = $message->getHeaders();
- //Remove all X-Foo headers
- $headers->removeAll('X-Foo');
+ //Remove the Subject: header
+ $headers->remove('Subject');
- //Remove only the second X-Foo header
- $headers->remove('X-Foo', 1);
+ //Remove all X-Foo headers
+ $headers->removeAll('X-Foo');
-### Modifying a Header's Content
+ //Remove only the second X-Foo header
+ $headers->remove('X-Foo', 1);
+
+Modifying a Header's Content
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To change a Header's content you should know what type of header it is and
then call it's appropriate setter method. All headers also have a
-`setFieldBodyModel()` method that accepts a mixed parameter and
+``setFieldBodyModel()`` method that accepts a mixed parameter and
delegates to the correct setter.
To modify an existing header:
- * Get the HeaderSet from the entity by via its `getHeaders()`
- method.
+* Get the HeaderSet from the entity by via its ``getHeaders()`` method.
- * Get the Header by using the HeaderSet's `get()`.
+* Get the Header by using the HeaderSet's ``get()``.
- * Call the Header's appropriate setter method or call the header's
- `setFieldBodyModel()` method.
+* Call the Header's appropriate setter method or call the header's
+ ``setFieldBodyModel()`` method.
The header will be updated inside the HeaderSet and the changes will be seen
when the message is sent.
- [php]
+.. code-block:: php
+
$headers = $message->getHeaders();
//Change the Subject: header
View
589 doc/08-Sending-Messages.rst
@@ -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