Message Headers

===============

Sometimes you'll want to add your own headers to a message or modify/remove

headers that are already present. You work with the message's HeaderSet to do

this.

Header Basics

-------------

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.

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 -- 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

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:

.. code-block:: php

    $message = Swift_Message::newInstance();

    //Fetch the HeaderSet from a Message object

    $headers = $message->getHeaders();

    $attachment = Swift_Attachment::fromPath('document.pdf');

    //Fetch the HeaderSet from an attachment object

    $headers = $attachment->getHeaders();

The job of the HeaderSet is to contain and manage instances of Header objects.

Depending upon the MIME entity the HeaderSet came from, the contents of the

HeaderSet will be different, since an attachment for example has a different

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:

.. code-block:: php

    foreach ($headers->getAll() as $header) {

      printf("%s<br />\n", $header->getFieldName());

    }

    /*

    Content-Transfer-Encoding

    Content-Type

    MIME-Version

    Date

    Message-ID

    From

    Subject

    To

    */

You can also dump out the rendered HeaderSet by calling its

``toString()`` method:

.. code-block:: php

    echo $headers->toString();

    /*

    Message-ID: <1234869991.499a9ee7f1d5e@swift.generated>

    Date: Tue, 17 Feb 2009 22:26:31 +1100

    Subject: Awesome subject!

    From: sender@example.org

    To: recipient@example.org

    MIME-Version: 1.0

    Content-Type: text/plain; charset=utf-8

    Content-Transfer-Encoding: quoted-printable

    */

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!). 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``.

.. code-block:: php

    foreach ($headers->getAll() as $header) {

      switch ($header->getFieldType()) {

        case Swift_Mime_Header::TYPE_TEXT: $type = 'text';

          break;

        case Swift_Mime_Header::TYPE_PARAMETERIZED: $type = 'parameterized';

          break;

        case Swift_Mime_Header::TYPE_MAILBOX: $type = 'mailbox';

          break;

        case Swift_Mime_Header::TYPE_DATE: $type = 'date';

          break;

        case Swift_Mime_Header::TYPE_ID: $type = 'ID';

          break;

        case Swift_Mime_Header::TYPE_PATH: $type = 'path';

          break;

      }

      printf("%s: is a %s header<br />\n", $header->getFieldName(), $type);

    }

    /*

    Content-Transfer-Encoding: is a text header

    Content-Type: is a parameterized header

    MIME-Version: is a text header

    Date: is a date header

    Message-ID: is a ID header

    From: is a mailbox header

    Subject: is a text header

    To: is a mailbox header

    */

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

exist within the HeaderSet.

Header Types

------------

Because all headers are modeled on different data (dates, addresses,

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 are the simplest type of Header. They contain textual information

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

probably the one you'd opt to use if you need to add a custom header to a

message. It represents text just like you'd think it does. If the text

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 -- 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.

.. code-block:: php

    $message = Swift_Message::newInstance();

    $headers = $message->getHeaders();

    $headers->addTextHeader('Your-Header-Name', 'the header value');

Changing the value of an existing text header is done by calling it's

``setValue()`` method.

.. code-block:: php

    $subject = $message->getHeaders()->getHeader('Subject');

    $subject->setValue('new subject');

When output via ``toString()``, a text header produces something

like the following:

.. code-block:: php

    $subject = $message->getHeaders()->getHeader('Subject');

    $subject->setValue('amazing subject line');

    echo $subject->toString();

    /*

    Subject: amazing subject line

    */

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.

.. code-block:: php

    $subject = $message->getHeaders()->getHeader('Subject');

    $subject->setValue('contains – dash');

    echo $subject->toString();

    /*

    Subject: contains =?utf-8?Q?=E2=80=93?= dash

    */

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

parameterized header since it contains charset information after the content

type.

The parameterized header type is a special type of text header. It extends the

text header by allowing additional information to follow it. All of the

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

key-value parameters.

.. code-block:: php

    $message = Swift_Message::newInstance();

    $headers = $message->getHeaders();

    $headers->addParameterizedHeader(

      'Header-Name', 'header value',

      array('foo' => 'bar')

      );

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()``

method (note the pluralization).

.. code-block:: php

    $type = $message->getHeaders()->getHeader('Content-Type');

    //setParameters() takes an associative array

    $type->setParameters(array(

      'name' => 'file.txt',

      'charset' => 'iso-8859-1'

      ));

    //setParameter() takes two args for $key and $value

    $type->setParameter('charset', 'iso-8859-1');

When output via ``toString()``, a parameterized header produces

something like the following:

.. code-block:: php

    $type = $message->getHeaders()->getHeader('Content-Type');

    $type->setValue('text/html');

    $type->setParameter('charset', 'utf-8');

    echo $type->toString();

    /*

    Content-Type: text/html; charset=utf-8

    */

If the header contains any characters that are outside of the US-ASCII range

however, they will be encoded, just like they are for text headers. This is

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.

.. code-block:: php

    $attachment = Swift_Attachment::newInstance();

    $disp = $attachment->getHeaders()->getHeader('Content-Disposition');

    $disp->setValue('attachment');

    $disp->setParameter('filename', 'report–may.pdf');

    echo $disp->toString();

    /*

    Content-Disposition: attachment; filename*=utf-8''report%E2%80%93may.pdf

    */

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

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

is used to create a correctly structured RFC 2822 formatted date such as

``Tue, 17 Feb 2009 22:26:31 +1100``.

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.

.. code-block:: php

    $message = Swift_Message::newInstance();

    $headers = $message->getHeaders();

    $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.

.. code-block:: php

    $date = $message->getHeaders()->getHeader('Date');

    $date->setTimestamp(time());

When output via ``toString()``, a date header produces something

like the following:

.. code-block:: php

    $date = $message->getHeaders()->getHeader('Date');

    echo $date->toString();

    /*

    Date: Wed, 18 Feb 2009 13:35:02 +1100

    */

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

represented by an associative array of email addresses and names.

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 -- 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.

.. code-block:: php

    $message = Swift_Message::newInstance();

    $headers = $message->getHeaders();

    $headers->addMailboxHeader('Your-Header-Name', array(

      'person1@example.org' => 'Person Name One',

      'person2@example.org',

      'person3@example.org',

      'person4@example.org' => 'Another named person'

      ));

Changing the value of an existing mailbox header is done by calling it's

``setNameAddresses()`` method.

.. code-block:: php

    $to = $message->getHeaders()->getHeader('To');

    $to->setNameAddresses(array(

      'joe@example.org' => 'Joe Bloggs',

      'john@example.org' => 'John Doe',

      'no-name@example.org'

      ));

If you don't wish to concern yourself with the complicated accepted input

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.

.. code-block:: php

    $to = $message->getHeaders()->getHeader('To');

    $to->setAddresses(array(

      'joe@example.org',

      'john@example.org',

      'no-name@example.org'

      ));

.. 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()``.

.. code-block:: php

    $to = $message->getHeaders()->getHeader('To');

    $to->setAddresses('joe-bloggs@example.org');

When output via ``toString()``, a mailbox header produces

something like the following:

.. code-block:: php

    $to = $message->getHeaders()->getHeader('To');

    $to->setNameAddresses(array(

      'person1@example.org' => 'Name of Person',

      'person2@example.org',

      'person3@example.org' => 'Another Person'

    ));

    echo $to->toString();

    /*

    To: Name of Person <person1@example.org>, person2@example.org, Another Person

     <person3@example.org>

    */

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>]]>``.

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

MUST conform to this structure, otherwise you'll get an Exception thrown at you

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.

.. code-block:: php

    $message = Swift_Message::newInstance();

    $headers = $message->getHeaders();

    $headers->addIdHeader('Your-Header-Name', '123456.unqiue@example.org');

Changing the value of an existing date header is done by calling its

``setId()`` method.

.. code-block:: php

    $msgId = $message->getHeaders()->getHeader('Message-ID');

    $msgId->setId(time() . '.' . uniqid('thing') . '@example.org');

When output via ``toString()``, an ID header produces something

like the following:

.. code-block:: php

    $msgId = $message->getHeaders()->getHeader('Message-ID');

    echo $msgId->toString();

    /*

    Message-ID: <1234955437.499becad62ec2@example.org>

    */