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 (see Text Headers). 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.

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

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

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

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

*/