(Grav GitSync) Automatic Commit from RealStickman
This commit is contained in:
parent
6d171c8aad
commit
6a1860d623
@ -1,11 +0,0 @@
|
||||
*.crt -crlf
|
||||
*.key -crlf
|
||||
*.srl -crlf
|
||||
*.pub -crlf
|
||||
*.priv -crlf
|
||||
*.txt -crlf
|
||||
|
||||
# ignore directories in the git-generated distributed .zip archive
|
||||
/doc/notes export-ignore
|
||||
/tests export-ignore
|
||||
/phpunit.xml.dist export-ignore
|
@ -1,44 +0,0 @@
|
||||
{
|
||||
"name": "swiftmailer/swiftmailer",
|
||||
"type": "library",
|
||||
"description": "Swiftmailer, free feature-rich PHP mailer",
|
||||
"keywords": ["mail","mailer","email"],
|
||||
"homepage": "https://swiftmailer.symfony.com",
|
||||
"license": "MIT",
|
||||
"authors": [
|
||||
{
|
||||
"name": "Chris Corbyn"
|
||||
},
|
||||
{
|
||||
"name": "Fabien Potencier",
|
||||
"email": "fabien@symfony.com"
|
||||
}
|
||||
],
|
||||
"require": {
|
||||
"php": ">=7.0.0",
|
||||
"egulias/email-validator": "^2.0|^3.1",
|
||||
"symfony/polyfill-iconv": "^1.0",
|
||||
"symfony/polyfill-mbstring": "^1.0",
|
||||
"symfony/polyfill-intl-idn": "^1.10"
|
||||
},
|
||||
"require-dev": {
|
||||
"mockery/mockery": "^1.0",
|
||||
"symfony/phpunit-bridge": "^4.4|^5.4"
|
||||
},
|
||||
"suggest": {
|
||||
"ext-intl": "Needed to support internationalized email addresses"
|
||||
},
|
||||
"autoload": {
|
||||
"files": ["lib/swift_required.php"]
|
||||
},
|
||||
"autoload-dev": {
|
||||
"psr-0": { "Swift_": "tests/unit" }
|
||||
},
|
||||
"extra": {
|
||||
"branch-alias": {
|
||||
"dev-master": "6.2-dev"
|
||||
}
|
||||
},
|
||||
"minimum-stability": "dev",
|
||||
"prefer-stable": true
|
||||
}
|
@ -1,621 +0,0 @@
|
||||
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_SimpleMimeEntity``. 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::
|
||||
|
||||
$message = new Swift_Message();
|
||||
|
||||
// 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::
|
||||
|
||||
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::
|
||||
|
||||
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``::
|
||||
|
||||
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::
|
||||
|
||||
$message = new Swift_Message();
|
||||
$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::
|
||||
|
||||
$subject = $message->getHeaders()->get('Subject');
|
||||
$subject->setValue('new subject');
|
||||
|
||||
When output via ``toString()``, a text header produces something like the
|
||||
following::
|
||||
|
||||
$subject = $message->getHeaders()->get('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::
|
||||
|
||||
$subject = $message->getHeaders()->get('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::
|
||||
|
||||
$message = new Swift_Message();
|
||||
$headers = $message->getHeaders();
|
||||
$headers->addParameterizedHeader(
|
||||
'Header-Name', 'header value',
|
||||
['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)::
|
||||
|
||||
$type = $message->getHeaders()->get('Content-Type');
|
||||
|
||||
// setParameters() takes an associative array
|
||||
$type->setParameters([
|
||||
'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::
|
||||
|
||||
$type = $message->getHeaders()->get('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::
|
||||
|
||||
$attachment = new Swift_Attachment();
|
||||
$disp = $attachment->getHeaders()->get('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 as a DateTimeImmutable object. The
|
||||
object is used to create a correctly structured RFC 2822 formatted date with
|
||||
timezone 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::
|
||||
|
||||
$message = new Swift_Message();
|
||||
$headers = $message->getHeaders();
|
||||
$headers->addDateHeader('Your-Header', new DateTimeImmutable('3 days ago'));
|
||||
|
||||
Changing the value of an existing date header is done by calling it's
|
||||
``setDateTime()`` method::
|
||||
|
||||
$date = $message->getHeaders()->get('Date');
|
||||
$date->setDateTime(new DateTimeImmutable());
|
||||
|
||||
When output via ``toString()``, a date header produces something like the
|
||||
following::
|
||||
|
||||
$date = $message->getHeaders()->get('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::
|
||||
|
||||
$message = new Swift_Message();
|
||||
$headers = $message->getHeaders();
|
||||
$headers->addMailboxHeader('Your-Header-Name', [
|
||||
'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::
|
||||
|
||||
$to = $message->getHeaders()->get('To');
|
||||
$to->setNameAddresses([
|
||||
'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::
|
||||
|
||||
$to = $message->getHeaders()->get('To');
|
||||
$to->setAddresses([
|
||||
'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()``::
|
||||
|
||||
$to = $message->getHeaders()->get('To');
|
||||
$to->setAddresses('joe-bloggs@example.org');
|
||||
|
||||
When output via ``toString()``, a mailbox header produces something like the
|
||||
following::
|
||||
|
||||
$to = $message->getHeaders()->get('To');
|
||||
$to->setNameAddresses([
|
||||
'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>
|
||||
|
||||
*/
|
||||
|
||||
Internationalized domains are automatically converted to IDN encoding::
|
||||
|
||||
$to = $message->getHeaders()->get('To');
|
||||
$to->setAddresses('joe@ëxämple.org');
|
||||
|
||||
echo $to->toString();
|
||||
|
||||
/*
|
||||
|
||||
To: joe@xn--xmple-gra1c.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, ``<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 to the 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::
|
||||
|
||||
$message = new Swift_Message();
|
||||
$headers = $message->getHeaders();
|
||||
$headers->addIdHeader('Your-Header-Name', '123456.unqiue@example.org');
|
||||
|
||||
Changing the value of an existing ID header is done by calling its ``setId()``
|
||||
method::
|
||||
|
||||
$msgId = $message->getHeaders()->get('Message-ID');
|
||||
$msgId->setId(time() . '.' . uniqid('thing') . '@example.org');
|
||||
|
||||
When output via ``toString()``, an ID header produces something like the
|
||||
following::
|
||||
|
||||
$msgId = $message->getHeaders()->get('Message-ID');
|
||||
echo $msgId->toString();
|
||||
|
||||
/*
|
||||
|
||||
Message-ID: <1234955437.499becad62ec2@example.org>
|
||||
|
||||
*/
|
||||
|
||||
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::
|
||||
|
||||
$message = new Swift_Message();
|
||||
$headers = $message->getHeaders();
|
||||
$headers->addPathHeader('Your-Header-Name', 'person@example.org');
|
||||
|
||||
Changing the value of an existing path header is done by calling its
|
||||
``setAddress()`` method::
|
||||
|
||||
$return = $message->getHeaders()->get('Return-Path');
|
||||
$return->setAddress('my-address@example.org');
|
||||
|
||||
When output via ``toString()``, a path header produces something like the
|
||||
following::
|
||||
|
||||
$return = $message->getHeaders()->get('Return-Path');
|
||||
$return->setAddress('person@example.org');
|
||||
echo $return->toString();
|
||||
|
||||
/*
|
||||
|
||||
Return-Path: <person@example.org>
|
||||
|
||||
*/
|
||||
|
||||
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
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
New headers can be added to the HeaderSet by using one of the provided
|
||||
``add..Header()`` methods.
|
||||
|
||||
The added header will appear in the message when it is sent::
|
||||
|
||||
// Adding a custom header to a message
|
||||
$message = new Swift_Message();
|
||||
$headers = $message->getHeaders();
|
||||
$headers->addTextHeader('X-Mine', 'something here');
|
||||
|
||||
// Adding a custom header to an attachment
|
||||
$attachment = Swift_Attachment::fromPath('/path/to/doc.pdf');
|
||||
$attachment->getHeaders()->addDateHeader('X-Created-Time', time());
|
||||
|
||||
Retrieving Headers
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Headers are retrieved through the HeaderSet's ``get()`` and ``getAll()``
|
||||
methods::
|
||||
|
||||
$headers = $message->getHeaders();
|
||||
|
||||
// Get the To: header
|
||||
$toHeader = $headers->get('To');
|
||||
|
||||
// Get all headers named "X-Foo"
|
||||
$fooHeaders = $headers->getAll('X-Foo');
|
||||
|
||||
// Get the second header named "X-Foo"
|
||||
$foo = $headers->get('X-Foo', 1);
|
||||
|
||||
// Get all headers that are present
|
||||
$all = $headers->getAll();
|
||||
|
||||
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 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::
|
||||
|
||||
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.
|
||||
|
||||
Check if a Header Exists
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
You can check if a named header is present in a HeaderSet by calling its
|
||||
``has()`` method::
|
||||
|
||||
$headers = $message->getHeaders();
|
||||
|
||||
// Check if the To: header exists
|
||||
if ($headers->has('To')) {
|
||||
echo 'To: exists';
|
||||
}
|
||||
|
||||
// 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';
|
||||
}
|
||||
|
||||
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.
|
||||
|
||||
Removing Headers
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
Removing a Header from the HeaderSet is done by calling the HeaderSet's
|
||||
``remove()`` or ``removeAll()`` methods::
|
||||
|
||||
$headers = $message->getHeaders();
|
||||
|
||||
// Remove the Subject: header
|
||||
$headers->remove('Subject');
|
||||
|
||||
// Remove all X-Foo headers
|
||||
$headers->removeAll('X-Foo');
|
||||
|
||||
// Remove only the second X-Foo header
|
||||
$headers->remove('X-Foo', 1);
|
||||
|
||||
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.
|
||||
|
||||
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 delegates to
|
||||
the correct setter::
|
||||
|
||||
The header will be updated inside the HeaderSet and the changes will be seen
|
||||
when the message is sent::
|
||||
|
||||
$headers = $message->getHeaders();
|
||||
|
||||
// Change the Subject: header
|
||||
$subj = $headers->get('Subject');
|
||||
$subj->setValue('new subject here');
|
||||
|
||||
// Change the To: header
|
||||
$to = $headers->get('To');
|
||||
$to->setNameAddresses([
|
||||
'person@example.org' => 'Person',
|
||||
'thing@example.org'
|
||||
]);
|
||||
|
||||
// Using the setFieldBodyModel() just delegates to the correct method
|
||||
// So here to calls setNameAddresses()
|
||||
$to->setFieldBodyModel([
|
||||
'person@example.org' => 'Person',
|
||||
'thing@example.org'
|
||||
]);
|
@ -1,12 +0,0 @@
|
||||
Swiftmailer
|
||||
===========
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
introduction
|
||||
messages
|
||||
headers
|
||||
sending
|
||||
plugins
|
||||
japanese
|
@ -1,67 +0,0 @@
|
||||
Swiftmailer: A feature-rich PHP Mailer
|
||||
======================================
|
||||
|
||||
Swift Mailer is a component based library for sending e-mails from PHP applications.
|
||||
|
||||
**Swiftmailer will stop being maintained at the end of November 2021.**
|
||||
|
||||
Please, move to `Symfony Mailer <https://symfony.com/doc/current/mailer.html>`_ at your earliest convenience.
|
||||
`Symfony Mailer <https://symfony.com/doc/current/mailer.html>`_ is the next evolution of Swiftmailer.
|
||||
It provides the same features with support for modern PHP code and support for third-party providers.
|
||||
|
||||
System Requirements
|
||||
-------------------
|
||||
|
||||
Swift Mailer requires PHP 7.0 or higher (``proc_*`` functions must be
|
||||
available).
|
||||
|
||||
Swift Mailer does not work when used with function overloading as implemented
|
||||
by ``mbstring`` when ``mbstring.func_overload`` is set to ``2``.
|
||||
|
||||
Installation
|
||||
------------
|
||||
|
||||
The recommended way to install Swiftmailer is via Composer:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ composer require "swiftmailer/swiftmailer:^6.0"
|
||||
|
||||
Basic Usage
|
||||
-----------
|
||||
|
||||
Here is the simplest way to send emails with Swift Mailer::
|
||||
|
||||
require_once '/path/to/vendor/autoload.php';
|
||||
|
||||
// Create the Transport
|
||||
$transport = (new Swift_SmtpTransport('smtp.example.org', 25))
|
||||
->setUsername('your username')
|
||||
->setPassword('your password')
|
||||
;
|
||||
|
||||
// Create the Mailer using your created Transport
|
||||
$mailer = new Swift_Mailer($transport);
|
||||
|
||||
// Create a message
|
||||
$message = (new Swift_Message('Wonderful Subject'))
|
||||
->setFrom(['john@doe.com' => 'John Doe'])
|
||||
->setTo(['receiver@domain.org', 'other@domain.org' => 'A name'])
|
||||
->setBody('Here is the message itself')
|
||||
;
|
||||
|
||||
// Send the message
|
||||
$result = $mailer->send($message);
|
||||
|
||||
You can also use Sendmail as a transport::
|
||||
|
||||
// Sendmail
|
||||
$transport = new Swift_SendmailTransport('/usr/sbin/sendmail -bs');
|
||||
|
||||
Getting Help
|
||||
------------
|
||||
|
||||
For general support, use `Stack Overflow <https://stackoverflow.com>`_.
|
||||
|
||||
For bug reports and feature requests, create a new ticket in `GitHub
|
||||
<https://github.com/swiftmailer/swiftmailer/issues>`_.
|
@ -1,19 +0,0 @@
|
||||
Using Swift Mailer for Japanese Emails
|
||||
======================================
|
||||
|
||||
To send emails in Japanese, you need to tweak the default configuration.
|
||||
|
||||
Call the ``Swift::init()`` method with the following code as early as possible
|
||||
in your code::
|
||||
|
||||
Swift::init(function () {
|
||||
Swift_DependencyContainer::getInstance()
|
||||
->register('mime.qpheaderencoder')
|
||||
->asAliasOf('mime.base64headerencoder');
|
||||
|
||||
Swift_Preferences::getInstance()->setCharset('iso-2022-jp');
|
||||
});
|
||||
|
||||
/* rest of code goes here */
|
||||
|
||||
That's all!
|
@ -1,949 +0,0 @@
|
||||
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
|
||||
---------------
|
||||
|
||||
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::
|
||||
|
||||
// Create the message
|
||||
$message = (new Swift_Message())
|
||||
|
||||
// Give the message a subject
|
||||
->setSubject('Your subject')
|
||||
|
||||
// Set the From address with an associative array
|
||||
->setFrom(['john@doe.com' => 'John Doe'])
|
||||
|
||||
// Set the To addresses with an associative array (setTo/setCc/setBcc)
|
||||
->setTo(['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 DateTimeInterface instance 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()``::
|
||||
|
||||
$message = new Swift_Message();
|
||||
$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 ``echo $message->toString();`` you would see something like this:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
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 ``new Swift_Message()``::
|
||||
|
||||
// Pass it as a parameter when you create the message
|
||||
$message = new Swift_Message('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 choose 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.
|
||||
|
||||
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::
|
||||
|
||||
// Pass it as a parameter when you create the message
|
||||
$message = new Swift_Message('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.
|
||||
|
||||
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.
|
||||
|
||||
The attachment will be presented to the recipient as a downloadable file with
|
||||
the same filename as the one you attached::
|
||||
|
||||
// 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.
|
||||
|
||||
The attachment will be attached in the normal way, but meta-data sent inside
|
||||
the email will rename the file to something else::
|
||||
|
||||
// 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 ``Swift_Attachment`` directly.
|
||||
|
||||
The attachment will be presented to the recipient as a downloadable file
|
||||
with the filename and content-type you specify::
|
||||
|
||||
// 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 = new Swift_Attachment($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 = (new Swift_Attachment())
|
||||
->setFilename('my-file.pdf')
|
||||
->setContentType('application/pdf')
|
||||
->setBody($data)
|
||||
;
|
||||
|
||||
.. 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.
|
||||
|
||||
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.
|
||||
|
||||
The attachment will be displayed within the email viewing window if the mail
|
||||
client knows how to display it::
|
||||
|
||||
// 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')
|
||||
);
|
||||
|
||||
.. 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.
|
||||
|
||||
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.
|
||||
|
||||
The file will be displayed with the message inline with the HTML wherever its ID
|
||||
is used as a ``src`` attribute::
|
||||
|
||||
// Create the message
|
||||
$message = new Swift_Message('My subject');
|
||||
|
||||
// Set the body
|
||||
$message->setBody(
|
||||
'<html>' .
|
||||
' <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>' .
|
||||
' <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'
|
||||
);
|
||||
|
||||
.. 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::
|
||||
|
||||
// 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>' .
|
||||
' <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 ``new Swift_Image()`` method.
|
||||
|
||||
The file will be displayed with the message inline with the HTML wherever its ID
|
||||
is used as a ``src`` attribute::
|
||||
|
||||
// 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 = new Swift_Message('My subject');
|
||||
|
||||
// Set the body
|
||||
$message->setBody(
|
||||
'<html>' .
|
||||
' <body>' .
|
||||
' Here is an image <img src="' . // Embed the file
|
||||
$message->embed(new Swift_Image($img_data, 'image.jpg', 'image/jpeg')) .
|
||||
'" alt="Image" />' .
|
||||
' Rest of message' .
|
||||
' </body>' .
|
||||
'</html>',
|
||||
'text/html' // Mark the content-type as HTML
|
||||
);
|
||||
|
||||
.. 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::
|
||||
|
||||
// If placing the embed() code inline becomes cumbersome
|
||||
// it's easy to do this in two steps
|
||||
$cid = $message->embed(new Swift_Image($img_data, 'image.jpg', 'image/jpeg'));
|
||||
|
||||
$message->setBody(
|
||||
'<html>' .
|
||||
' <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.
|
||||
|
||||
Make sure to add only valid email addresses as recipients. If you try to add an
|
||||
invalid email address with ``setTo()``, ``setCc()`` or ``setBcc()``, Swift
|
||||
Mailer will throw a ``Swift_RfcComplianceException``.
|
||||
|
||||
If you add recipients automatically based on a data source that may contain
|
||||
invalid email addresses, you can prevent possible exceptions by validating the
|
||||
addresses using::
|
||||
|
||||
use Egulias\EmailValidator\EmailValidator;
|
||||
use Egulias\EmailValidator\Validation\RFCValidation;
|
||||
|
||||
$validator = new EmailValidator();
|
||||
$validator->isValid("example@example.com", new RFCValidation()); //true
|
||||
|
||||
and only adding addresses that validate. Another way would be to wrap your ``setTo()``, ``setCc()`` and
|
||||
``setBcc()`` calls in a try-catch block and handle the
|
||||
``Swift_RfcComplianceException`` in the catch block.
|
||||
|
||||
.. 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::
|
||||
|
||||
$message->setFrom('some@address.tld');
|
||||
|
||||
If you want to include a name then you must use an associative array::
|
||||
|
||||
$message->setFrom(['some@address.tld' => 'The Name']);
|
||||
|
||||
If you want to include multiple addresses then you must use an array::
|
||||
|
||||
$message->setTo(['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::
|
||||
|
||||
$message->setTo([
|
||||
'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( ... )``, 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::
|
||||
|
||||
// Using setTo() to set all recipients in one go
|
||||
$message->setTo([
|
||||
'person1@example.org',
|
||||
'person2@otherdomain.org' => 'Person 2 Name',
|
||||
'person3@example.org',
|
||||
'person4@example.org',
|
||||
'person5@example.org' => 'Person 5 Name'
|
||||
]);
|
||||
|
||||
.. 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::
|
||||
|
||||
// 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( ... )``, 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::
|
||||
|
||||
// Using setTo() to set all recipients in one go
|
||||
$message->setTo([
|
||||
'person1@example.org',
|
||||
'person2@otherdomain.org' => 'Person 2 Name',
|
||||
'person3@example.org',
|
||||
'person4@example.org',
|
||||
'person5@example.org' => 'Person 5 Name'
|
||||
]);
|
||||
|
||||
.. 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::
|
||||
|
||||
// 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( ... )``, 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::
|
||||
|
||||
// Using setBcc() to set all recipients in one go
|
||||
$message->setBcc([
|
||||
'person1@example.org',
|
||||
'person2@otherdomain.org' => 'Person 2 Name',
|
||||
'person3@example.org',
|
||||
'person4@example.org',
|
||||
'person5@example.org' => 'Person 5 Name'
|
||||
]);
|
||||
|
||||
.. 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::
|
||||
|
||||
// Using addBcc() to add recipients iteratively
|
||||
$message->addBcc('person1@example.org');
|
||||
$message->addBcc('person2@example.org', 'Person 2 Name');
|
||||
|
||||
.. sidebar:: Internationalized Email Addresses
|
||||
|
||||
Traditionally only ASCII characters have been allowed in email addresses.
|
||||
With the introduction of internationalized domain names (IDNs), non-ASCII
|
||||
characters may appear in the domain name. By default, Swiftmailer encodes
|
||||
such domain names in Punycode (e.g. xn--xample-ova.invalid). This is
|
||||
compatible with all mail servers.
|
||||
|
||||
RFC 6531 introduced an SMTP extension, SMTPUTF8, that allows non-ASCII
|
||||
characters in email addresses on both sides of the @ sign. To send to such
|
||||
addresses, your outbound SMTP server must support the SMTPUTF8 extension.
|
||||
You should use the ``Swift_AddressEncoder_Utf8AddressEncoder`` address
|
||||
encoder and enable the ``Swift_Transport_Esmtp_SmtpUtf8Handler`` SMTP
|
||||
extension handler::
|
||||
|
||||
$smtpUtf8 = new Swift_Transport_Esmtp_SmtpUtf8Handler();
|
||||
$transport->setExtensionHandlers([$smtpUtf8]);
|
||||
$utf8Encoder = new Swift_AddressEncoder_Utf8AddressEncoder();
|
||||
$transport->setAddressEncoder($utf8Encoder);
|
||||
|
||||
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 realize 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.
|
||||
|
||||
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.
|
||||
|
||||
::
|
||||
|
||||
// Set a single From: address
|
||||
$message->setFrom('your@address.tld');
|
||||
|
||||
// Set a From: address including a name
|
||||
$message->setFrom(['your@address.tld' => 'Your Name']);
|
||||
|
||||
// Set multiple From: addresses if multiple people wrote the email
|
||||
$message->setFrom([
|
||||
'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.
|
||||
|
||||
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::
|
||||
|
||||
$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.
|
||||
|
||||
Bounce notifications will be sent to this address::
|
||||
|
||||
$message->setReturnPath('bounces@address.tld');
|
||||
|
||||
Signed/Encrypted Message
|
||||
------------------------
|
||||
|
||||
To increase the integrity/security of a message it is possible to sign and/or
|
||||
encrypt an message using one or multiple signers.
|
||||
|
||||
S/MIME
|
||||
~~~~~~
|
||||
|
||||
S/MIME can sign and/or encrypt a message using the OpenSSL extension.
|
||||
|
||||
When signing a message, the signer creates a signature of the entire content of
|
||||
the message (including attachments).
|
||||
|
||||
The certificate and private key must be PEM encoded, and can be either created
|
||||
using for example OpenSSL or obtained at an official Certificate Authority (CA).
|
||||
|
||||
**The recipient must have the CA certificate in the list of trusted issuers in
|
||||
order to verify the signature.**
|
||||
|
||||
**Make sure the certificate supports emailProtection.**
|
||||
|
||||
When using OpenSSL this can done by the including the *-addtrust
|
||||
emailProtection* parameter when creating the certificate::
|
||||
|
||||
$message = new Swift_Message();
|
||||
|
||||
$smimeSigner = new Swift_Signers_SMimeSigner();
|
||||
$smimeSigner->setSignCertificate('/path/to/certificate.pem', '/path/to/private-key.pem');
|
||||
$message->attachSigner($smimeSigner);
|
||||
|
||||
When the private key is secured using a passphrase use the following instead::
|
||||
|
||||
$message = new Swift_Message();
|
||||
|
||||
$smimeSigner = new Swift_Signers_SMimeSigner();
|
||||
$smimeSigner->setSignCertificate('/path/to/certificate.pem', ['/path/to/private-key.pem', 'passphrase']);
|
||||
$message->attachSigner($smimeSigner);
|
||||
|
||||
By default the signature is added as attachment, making the message still
|
||||
readable for mailing agents not supporting signed messages.
|
||||
|
||||
Storing the message as binary is also possible but not recommended::
|
||||
|
||||
$smimeSigner->setSignCertificate('/path/to/certificate.pem', '/path/to/private-key.pem', PKCS7_BINARY);
|
||||
|
||||
When encrypting the message (also known as enveloping), the entire message
|
||||
(including attachments) is encrypted using a certificate, and the recipient can
|
||||
then decrypt the message using corresponding private key.
|
||||
|
||||
Encrypting ensures nobody can read the contents of the message without the
|
||||
private key.
|
||||
|
||||
Normally the recipient provides a certificate for encrypting and keeping the
|
||||
decryption key private.
|
||||
|
||||
Using both signing and encrypting is also possible::
|
||||
|
||||
$message = new Swift_Message();
|
||||
|
||||
$smimeSigner = new Swift_Signers_SMimeSigner();
|
||||
$smimeSigner->setSignCertificate('/path/to/sign-certificate.pem', '/path/to/private-key.pem');
|
||||
$smimeSigner->setEncryptCertificate('/path/to/encrypt-certificate.pem');
|
||||
$message->attachSigner($smimeSigner);
|
||||
|
||||
The used encryption cipher can be set as the second parameter of
|
||||
setEncryptCertificate()
|
||||
|
||||
See https://secure.php.net/manual/openssl.ciphers for a list of supported ciphers.
|
||||
|
||||
By default the message is first signed and then encrypted, this can be changed
|
||||
by adding::
|
||||
|
||||
$smimeSigner->setSignThenEncrypt(false);
|
||||
|
||||
**Changing this is not recommended as most mail agents don't support this
|
||||
none-standard way.**
|
||||
|
||||
Only when having trouble with sign then encrypt method, this should be changed.
|
||||
|
||||
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()``::
|
||||
|
||||
$message->setReadReceiptTo('your@address.tld');
|
||||
|
||||
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.
|
||||
|
||||
Setting the Character Set
|
||||
-------------------------
|
||||
|
||||
The character set of the message (and its 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::
|
||||
|
||||
// Approach 1: Change the global setting (suggested)
|
||||
Swift_Preferences::getInstance()->setCharset('iso-8859-2');
|
||||
|
||||
// Approach 2: Call the setCharset() method of the message
|
||||
$message = (new Swift_Message())
|
||||
->setCharset('iso-8859-2');
|
||||
|
||||
// Approach 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 Encoding
|
||||
--------------------
|
||||
|
||||
The body of each MIME part needs to be encoded. Binary attachments are encoded
|
||||
in base64 using the ``Swift_Mime_ContentEncoder_Base64ContentEncoder``. Text
|
||||
parts are traditionally encoded in quoted-printable using
|
||||
``Swift_Mime_ContentEncoder_QpContentEncoder`` or
|
||||
``Swift_Mime_ContentEncoder_NativeQpContentEncoder``.
|
||||
|
||||
The encoder of the message or MIME part is set with the ``setEncoder()`` method.
|
||||
|
||||
Quoted-printable is the safe choice, because it converts 8-bit text as 7-bit.
|
||||
Most modern SMTP servers support 8-bit text. This is advertised via the 8BITMIME
|
||||
SMTP extension. If your outbound SMTP server supports this SMTP extension, and
|
||||
it supports downgrading the message (e.g converting to quoted-printable on the
|
||||
fly) when delivering to a downstream server that does not support the extension,
|
||||
you may wish to use ``Swift_Mime_ContentEncoder_PlainContentEncoder`` in
|
||||
``8bit`` mode instead. This has the advantage that the source data is slightly
|
||||
more readable and compact, especially for non-Western languages.
|
||||
|
||||
$eightBitMime = new Swift_Transport_Esmtp_EightBitMimeHandler();
|
||||
$transport->setExtensionHandlers([$eightBitMime]);
|
||||
$plainEncoder = new Swift_Mime_ContentEncoder_PlainContentEncoder('8bit');
|
||||
$message->setEncoder($plainEncoder);
|
||||
|
||||
Setting the Line Length
|
||||
-----------------------
|
||||
|
||||
The length of lines in a message can be changed by using the
|
||||
``setMaxLineLength()`` method on the message::
|
||||
|
||||
$message->setMaxLineLength(1000);
|
||||
|
||||
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
|
||||
|
||||
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.
|
||||
|
||||
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::
|
||||
|
||||
// Indicate "High" priority
|
||||
$message->setPriority(2);
|
||||
|
||||
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:
|
||||
|
||||
* ``Swift_Mime_SimpleMessage::PRIORITY_HIGHEST``: 1
|
||||
* ``Swift_Mime_SimpleMessage::PRIORITY_HIGH``: 2
|
||||
* ``Swift_Mime_SimpleMessage::PRIORITY_NORMAL``: 3
|
||||
* ``Swift_Mime_SimpleMessage::PRIORITY_LOW``: 4
|
||||
* ``Swift_Mime_SimpleMessage::PRIORITY_LOWEST``: 5
|
||||
|
||||
::
|
||||
|
||||
// Or use the constant to be more explicit
|
||||
$message->setPriority(Swift_Mime_SimpleMessage::PRIORITY_HIGH);
|
@ -1,337 +0,0 @@
|
||||
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.
|
||||
|
||||
AntiFlood Plugin
|
||||
----------------
|
||||
|
||||
Many SMTP servers have limits on the number of messages that may be sent during
|
||||
any single SMTP connection. The AntiFlood plugin provides a way to stay within
|
||||
this limit while still managing a large number of emails.
|
||||
|
||||
A typical limit for a single connection is 100 emails. If the server you
|
||||
connect to imposes such a limit, it expects you to disconnect after that number
|
||||
of emails has been sent. You could manage this manually within a loop, but the
|
||||
AntiFlood plugin provides the necessary wrapper code so that you don't need to
|
||||
worry about this logic.
|
||||
|
||||
Regardless of limits imposed by the server, it's usually a good idea to be
|
||||
conservative with the resources of the SMTP server. Sending will become
|
||||
sluggish if the server is being over-used so using the AntiFlood plugin will
|
||||
not be a bad idea even if no limits exist.
|
||||
|
||||
The AntiFlood plugin's logic is basically to disconnect and the immediately
|
||||
re-connect with the SMTP server every X number of emails sent, where X is a
|
||||
number you specify to the plugin.
|
||||
|
||||
You can also specify a time period in seconds that Swift Mailer should pause
|
||||
for between the disconnect/re-connect process. It's a good idea to pause for a
|
||||
short time (say 30 seconds every 100 emails) simply to give the SMTP server a
|
||||
chance to process its queue and recover some resources.
|
||||
|
||||
Using the AntiFlood Plugin
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The AntiFlood Plugin -- like all plugins -- is added with the Mailer class's
|
||||
``registerPlugin()`` method. It takes two constructor parameters: the number of
|
||||
emails to pause after, and optionally the number of seconds to pause for.
|
||||
|
||||
When Swift Mailer sends messages it will count the number of messages that have
|
||||
been sent since the last re-connect. Once the number hits your specified
|
||||
threshold it will disconnect and re-connect, optionally pausing for a specified
|
||||
amount of time::
|
||||
|
||||
// Create the Mailer using any Transport
|
||||
$mailer = new Swift_Mailer(
|
||||
new Swift_SmtpTransport('smtp.example.org', 25)
|
||||
);
|
||||
|
||||
// Use AntiFlood to re-connect after 100 emails
|
||||
$mailer->registerPlugin(new Swift_Plugins_AntiFloodPlugin(100));
|
||||
|
||||
// And specify a time in seconds to pause for (30 secs)
|
||||
$mailer->registerPlugin(new Swift_Plugins_AntiFloodPlugin(100, 30));
|
||||
|
||||
// Continue sending as normal
|
||||
for ($lotsOfRecipients as $recipient) {
|
||||
...
|
||||
|
||||
$mailer->send( ... );
|
||||
}
|
||||
|
||||
Throttler Plugin
|
||||
----------------
|
||||
|
||||
If your SMTP server has restrictions in place to limit the rate at which you
|
||||
send emails, then your code will need to be aware of this rate-limiting. The
|
||||
Throttler plugin makes Swift Mailer run at a rate-limited speed.
|
||||
|
||||
Many shared hosts don't open their SMTP servers as a free-for-all. Usually they
|
||||
have policies in place (probably to discourage spammers) that only allow you to
|
||||
send a fixed number of emails per-hour/day.
|
||||
|
||||
The Throttler plugin supports two modes of rate-limiting and with each, you
|
||||
will need to do that math to figure out the values you want. The plugin can
|
||||
limit based on the number of emails per minute, or the number of
|
||||
bytes-transferred per-minute.
|
||||
|
||||
Using the Throttler Plugin
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The Throttler Plugin -- like all plugins -- is added with the Mailer class'
|
||||
``registerPlugin()`` method. It has two required constructor parameters that
|
||||
tell it how to do its rate-limiting.
|
||||
|
||||
When Swift Mailer sends messages it will keep track of the rate at which
|
||||
sending messages is occurring. If it realises that sending is happening too
|
||||
fast, it will cause your program to ``sleep()`` for enough time to average out
|
||||
the rate::
|
||||
|
||||
// Create the Mailer using any Transport
|
||||
$mailer = new Swift_Mailer(
|
||||
new Swift_SmtpTransport('smtp.example.org', 25)
|
||||
);
|
||||
|
||||
// Rate limit to 100 emails per-minute
|
||||
$mailer->registerPlugin(new Swift_Plugins_ThrottlerPlugin(
|
||||
100, Swift_Plugins_ThrottlerPlugin::MESSAGES_PER_MINUTE
|
||||
));
|
||||
|
||||
// Rate limit to 10MB per-minute
|
||||
$mailer->registerPlugin(new Swift_Plugins_ThrottlerPlugin(
|
||||
1024 * 1024 * 10, Swift_Plugins_ThrottlerPlugin::BYTES_PER_MINUTE
|
||||
));
|
||||
|
||||
// Continue sending as normal
|
||||
for ($lotsOfRecipients as $recipient) {
|
||||
...
|
||||
|
||||
$mailer->send( ... );
|
||||
}
|
||||
|
||||
Logger Plugin
|
||||
-------------
|
||||
|
||||
The Logger plugins helps with debugging during the process of sending. It can
|
||||
help to identify why an SMTP server is rejecting addresses, or any other
|
||||
hard-to-find problems that may arise.
|
||||
|
||||
The Logger plugin comes in two parts. There's the plugin itself, along with one
|
||||
of a number of possible Loggers that you may choose to use. For example, the
|
||||
logger may output messages directly in realtime, or it may capture messages in
|
||||
an array.
|
||||
|
||||
One other notable feature is the way in which the Logger plugin changes
|
||||
Exception messages. If Exceptions are being thrown but the error message does
|
||||
not provide conclusive information as to the source of the problem (such as an
|
||||
ambiguous SMTP error) the Logger plugin includes the entire SMTP transcript in
|
||||
the error message so that debugging becomes a simpler task.
|
||||
|
||||
There are a few available Loggers included with Swift Mailer, but writing your
|
||||
own implementation is incredibly simple and is achieved by creating a short
|
||||
class that implements the ``Swift_Plugins_Logger`` interface.
|
||||
|
||||
* ``Swift_Plugins_Loggers_ArrayLogger``: Keeps a collection of log messages
|
||||
inside an array. The array content can be cleared or dumped out to the screen.
|
||||
|
||||
* ``Swift_Plugins_Loggers_EchoLogger``: Prints output to the screen in
|
||||
realtime. Handy for very rudimentary debug output.
|
||||
|
||||
Using the Logger Plugin
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The Logger Plugin -- like all plugins -- is added with the Mailer class'
|
||||
``registerPlugin()`` method. It accepts an instance of ``Swift_Plugins_Logger``
|
||||
in its constructor.
|
||||
|
||||
When Swift Mailer sends messages it will keep a log of all the interactions
|
||||
with the underlying Transport being used. Depending upon the Logger that has
|
||||
been used the behaviour will differ, but all implementations offer a way to get
|
||||
the contents of the log::
|
||||
|
||||
// Create the Mailer using any Transport
|
||||
$mailer = new Swift_Mailer(
|
||||
new Swift_SmtpTransport('smtp.example.org', 25)
|
||||
);
|
||||
|
||||
// To use the ArrayLogger
|
||||
$logger = new Swift_Plugins_Loggers_ArrayLogger();
|
||||
$mailer->registerPlugin(new Swift_Plugins_LoggerPlugin($logger));
|
||||
|
||||
// Or to use the Echo Logger
|
||||
$logger = new Swift_Plugins_Loggers_EchoLogger();
|
||||
$mailer->registerPlugin(new Swift_Plugins_LoggerPlugin($logger));
|
||||
|
||||
// Continue sending as normal
|
||||
for ($lotsOfRecipients as $recipient) {
|
||||
...
|
||||
|
||||
$mailer->send( ... );
|
||||
}
|
||||
|
||||
// Dump the log contents
|
||||
// NOTE: The EchoLogger dumps in realtime so dump() does nothing for it
|
||||
echo $logger->dump();
|
||||
|
||||
Decorator Plugin
|
||||
----------------
|
||||
|
||||
Often there's a need to send the same message to multiple recipients, but with
|
||||
tiny variations such as the recipient's name being used inside the message
|
||||
body. The Decorator plugin aims to provide a solution for allowing these small
|
||||
differences.
|
||||
|
||||
The decorator plugin works by intercepting the sending process of Swift Mailer,
|
||||
reading the email address in the To: field and then looking up a set of
|
||||
replacements for a template.
|
||||
|
||||
While the use of this plugin is simple, it is probably the most commonly
|
||||
misunderstood plugin due to the way in which it works. The typical mistake
|
||||
users make is to try registering the plugin multiple times (once for each
|
||||
recipient) -- inside a loop for example. This is incorrect.
|
||||
|
||||
The Decorator plugin should be registered just once, but containing the list of
|
||||
all recipients prior to sending. It will use this list of recipients to find
|
||||
the required replacements during sending.
|
||||
|
||||
Using the Decorator Plugin
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
To use the Decorator plugin, simply create an associative array of replacements
|
||||
based on email addresses and then use the mailer's ``registerPlugin()`` method
|
||||
to add the plugin.
|
||||
|
||||
First create an associative array of replacements based on the email addresses
|
||||
you'll be sending the message to.
|
||||
|
||||
.. note::
|
||||
|
||||
The replacements array becomes a 2-dimensional array whose keys are the
|
||||
email addresses and whose values are an associative array of replacements
|
||||
for that email address. The curly braces used in this example can be any
|
||||
type of syntax you choose, provided they match the placeholders in your
|
||||
email template::
|
||||
|
||||
$replacements = [];
|
||||
foreach ($users as $user) {
|
||||
$replacements[$user['email']] = [
|
||||
'{username}'=>$user['username'],
|
||||
'{resetcode}'=>$user['resetcode']
|
||||
];
|
||||
}
|
||||
|
||||
Now create an instance of the Decorator plugin using this array of replacements
|
||||
and then register it with the Mailer. Do this only once!
|
||||
|
||||
::
|
||||
|
||||
$decorator = new Swift_Plugins_DecoratorPlugin($replacements);
|
||||
|
||||
$mailer->registerPlugin($decorator);
|
||||
|
||||
When you create your message, replace elements in the body (and/or the subject
|
||||
line) with your placeholders::
|
||||
|
||||
$message = (new Swift_Message())
|
||||
->setSubject('Important notice for {username}')
|
||||
->setBody(
|
||||
"Hello {username}, you requested to reset your password.\n" .
|
||||
"Please visit https://example.com/pwreset and use the reset code {resetcode} to set a new password."
|
||||
)
|
||||
;
|
||||
|
||||
foreach ($users as $user) {
|
||||
$message->addTo($user['email']);
|
||||
}
|
||||
|
||||
When you send this message to each of your recipients listed in your
|
||||
``$replacements`` array they will receive a message customized for just
|
||||
themselves. For example, the message used above when received may appear like
|
||||
this to one user:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
Subject: Important notice for smilingsunshine2009
|
||||
|
||||
Hello smilingsunshine2009, you requested to reset your password.
|
||||
Please visit https://example.com/pwreset and use the reset code 183457 to set a new password.
|
||||
|
||||
While another use may receive the message as:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
Subject: Important notice for billy-bo-bob
|
||||
|
||||
Hello billy-bo-bob, you requested to reset your password.
|
||||
Please visit https://example.com/pwreset and use the reset code 539127 to set a new password.
|
||||
|
||||
While the decorator plugin provides a means to solve this problem, there are
|
||||
various ways you could tackle this problem without the need for a plugin. We're
|
||||
trying to come up with a better way ourselves and while we have several
|
||||
(obvious) ideas we don't quite have the perfect solution to go ahead and
|
||||
implement it. Watch this space.
|
||||
|
||||
Providing Your Own Replacements Lookup for the Decorator
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Filling an array with replacements may not be the best solution for providing
|
||||
replacement information to the decorator. If you have a more elegant algorithm
|
||||
that performs replacement lookups on-the-fly you may provide your own
|
||||
implementation.
|
||||
|
||||
Providing your own replacements lookup implementation for the Decorator is
|
||||
simply a matter of passing an instance of
|
||||
``Swift_Plugins_Decorator_Replacements`` to the decorator plugin's constructor,
|
||||
rather than passing in an array.
|
||||
|
||||
The Replacements interface is very simple to implement since it has just one
|
||||
method: ``getReplacementsFor($address)``.
|
||||
|
||||
Imagine you want to look up replacements from a database on-the-fly, you might
|
||||
provide an implementation that does this. You need to create a small class::
|
||||
|
||||
class DbReplacements implements Swift_Plugins_Decorator_Replacements {
|
||||
public function getReplacementsFor($address) {
|
||||
global $db; // Your PDO instance with a connection to your database
|
||||
$query = $db->prepare(
|
||||
"SELECT * FROM `users` WHERE `email` = ?"
|
||||
);
|
||||
|
||||
$query->execute([$address]);
|
||||
|
||||
if ($row = $query->fetch(PDO::FETCH_ASSOC)) {
|
||||
return [
|
||||
'{username}'=>$row['username'],
|
||||
'{resetcode}'=>$row['resetcode']
|
||||
];
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
Now all you need to do is pass an instance of your class into the Decorator
|
||||
plugin's constructor instead of passing an array::
|
||||
|
||||
$decorator = new Swift_Plugins_DecoratorPlugin(new DbReplacements());
|
||||
|
||||
$mailer->registerPlugin($decorator);
|
||||
|
||||
For each message sent, the plugin will call your class'
|
||||
``getReplacementsFor()`` method to find the array of replacements it needs.
|
||||
|
||||
.. note::
|
||||
|
||||
If your lookup algorithm is case sensitive, you should transform the
|
||||
``$address`` argument as appropriate -- for example by passing it through
|
||||
``strtolower()``.
|
@ -1,464 +0,0 @@
|
||||
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.
|
||||
|
||||
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::
|
||||
|
||||
// Create the Transport
|
||||
$transport = (new Swift_SmtpTransport('smtp.example.org', 25))
|
||||
->setUsername('your username')
|
||||
->setPassword('your password')
|
||||
;
|
||||
|
||||
/*
|
||||
You could alternatively use a different transport such as Sendmail:
|
||||
|
||||
// Sendmail
|
||||
$transport = new Swift_SendmailTransport('/usr/sbin/sendmail -bs');
|
||||
*/
|
||||
|
||||
// Create the Mailer using your created Transport
|
||||
$mailer = new Swift_Mailer($transport);
|
||||
|
||||
// Create a message
|
||||
$message = (new Swift_Message('Wonderful Subject'))
|
||||
->setFrom(['john@doe.com' => 'John Doe'])
|
||||
->setTo(['receiver@domain.org', 'other@domain.org' => 'A name'])
|
||||
->setBody('Here is the message itself')
|
||||
;
|
||||
|
||||
// Send the message
|
||||
$result = $mailer->send($message);
|
||||
|
||||
Transport Types
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
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::
|
||||
|
||||
* ``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_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).
|
||||
|
||||
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`` (SMTPS = SMTP over TLS) and ``tls``
|
||||
(SMTP with STARTTLS) 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.
|
||||
|
||||
A connection to the SMTP server will be established upon the first call to
|
||||
``send()``::
|
||||
|
||||
// Create the Transport
|
||||
$transport = new Swift_SmtpTransport('smtp.example.org', 25);
|
||||
|
||||
// Create the Mailer using your created Transport
|
||||
$mailer = new Swift_Mailer($transport);
|
||||
|
||||
/*
|
||||
It's also possible to use multiple method calls
|
||||
|
||||
$transport = (new Swift_SmtpTransport())
|
||||
->setHost('smtp.example.org')
|
||||
->setPort(25)
|
||||
;
|
||||
*/
|
||||
|
||||
Encrypted SMTP
|
||||
^^^^^^^^^^^^^^
|
||||
|
||||
You can use ``ssl`` (SMTPS) or ``tls`` (STARTTLS) encryption with the SMTP Transport
|
||||
by specifying it as a parameter or with a method call::
|
||||
|
||||
// Create the Transport
|
||||
// Option #1: SMTPS = SMTP over TLS (always encrypted):
|
||||
$transport = new Swift_SmtpTransport('smtp.example.org', 587, 'ssl');
|
||||
// Option #2: SMTP with STARTTLS (best effort encryption):
|
||||
$transport = new Swift_SmtpTransport('smtp.example.org', 587, 'tls');
|
||||
|
||||
// Create the Mailer using your created Transport
|
||||
$mailer = new Swift_Mailer($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 SMTPS or STARTTLS 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()``.
|
||||
|
||||
.. note::
|
||||
If you are using Mailcatcher_, make sure you do not set the encryption
|
||||
for the ``Swift_SmtpTransport``, since Mailcatcher does not support encryption.
|
||||
|
||||
.. note::
|
||||
When in doubt, try ``ssl`` first for higher security, since the communication
|
||||
is always encrypted.
|
||||
|
||||
.. note::
|
||||
Usually, port 587 or 465 is used for encrypted SMTP. Check the documentation
|
||||
of your mail provider.
|
||||
|
||||
SMTP with a Username and Password
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Some servers require authentication. You can provide a username and password
|
||||
with ``setUsername()`` and ``setPassword()`` methods::
|
||||
|
||||
// Create the Transport the call setUsername() and setPassword()
|
||||
$transport = (new Swift_SmtpTransport('smtp.example.org', 25))
|
||||
->setUsername('username')
|
||||
->setPassword('password')
|
||||
;
|
||||
|
||||
// Create the Mailer using your created Transport
|
||||
$mailer = new Swift_Mailer($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_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.
|
||||
|
||||
The Sendmail Transport
|
||||
......................
|
||||
|
||||
The Sendmail Transport sends messages by communicating with a locally installed
|
||||
MTA -- such as ``sendmail``.
|
||||
|
||||
The Sendmail Transport, ``Swift_SendmailTransport`` does not directly connect
|
||||
to any remote services. It is designed for Linux servers that have ``sendmail``
|
||||
installed. The Transport starts a local ``sendmail`` process and sends messages
|
||||
to it. Usually the ``sendmail`` process will respond quickly as it spools your
|
||||
messages to disk before sending them.
|
||||
|
||||
The Transport is named the Sendmail Transport for historical reasons
|
||||
(``sendmail`` was the "standard" UNIX tool for sending e-mail for years). It
|
||||
will send messages using other transfer agents such as Exim or Postfix despite
|
||||
its name, provided they have the relevant sendmail wrappers so that they can be
|
||||
started with the correct command-line flags.
|
||||
|
||||
It's a common misconception that because the Sendmail Transport returns a
|
||||
result very quickly it must therefore deliver messages to recipients quickly --
|
||||
this is not true. It's not slow by any means, but it's certainly not faster
|
||||
than SMTP when it comes to getting messages to the intended recipients. This is
|
||||
because sendmail itself sends the messages over SMTP once they have been
|
||||
quickly spooled to disk.
|
||||
|
||||
The Sendmail Transport has the potential to be just as smart of the SMTP
|
||||
Transport when it comes to notifying Swift Mailer about which recipients were
|
||||
rejected, but in reality the majority of locally installed ``sendmail``
|
||||
instances are not configured well enough to provide any useful feedback. As
|
||||
such Swift Mailer may report successful deliveries where they did in fact fail
|
||||
before they even left your server.
|
||||
|
||||
You can run the Sendmail Transport in two different modes specified by command
|
||||
line flags:
|
||||
|
||||
* "``-bs``" runs in SMTP mode so theoretically it will act like the SMTP
|
||||
Transport
|
||||
|
||||
* "``-t``" runs in piped mode with no feedback, but theoretically faster,
|
||||
though not advised
|
||||
|
||||
You can think of the Sendmail Transport as a sort of asynchronous SMTP
|
||||
Transport -- though if you have problems with delivery failures you should try
|
||||
using the SMTP Transport instead. Swift Mailer isn't doing the work here, it's
|
||||
simply passing the work to somebody else (i.e. ``sendmail``).
|
||||
|
||||
Using the Sendmail Transport
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
To use the Sendmail Transport you simply need to call ``new
|
||||
Swift_SendmailTransport()`` with the command as a parameter.
|
||||
|
||||
To use the Sendmail Transport you need to know where ``sendmail`` or another
|
||||
MTA exists on the server. Swift Mailer uses a default value of
|
||||
``/usr/sbin/sendmail``, which should work on most systems.
|
||||
|
||||
You specify the entire command as a parameter (i.e. including the command line
|
||||
flags). Swift Mailer supports operational modes of "``-bs``" (default) and
|
||||
"``-t``".
|
||||
|
||||
.. note::
|
||||
|
||||
If you run sendmail in "``-t``" mode you will get no feedback as to whether
|
||||
or not sending has succeeded. Use "``-bs``" unless you have a reason not to.
|
||||
|
||||
A sendmail process will be started upon the first call to ``send()``. If the
|
||||
process cannot be started successfully an Exception of type
|
||||
``Swift_TransportException`` will be thrown::
|
||||
|
||||
// Create the Transport
|
||||
$transport = new Swift_SendmailTransport('/usr/sbin/exim -bs');
|
||||
|
||||
// Create the Mailer using your created Transport
|
||||
$mailer = new Swift_Mailer($transport);
|
||||
|
||||
Available Methods for Sending Messages
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The Mailer class offers one method for sending Messages -- ``send()``.
|
||||
|
||||
When a message is sent in Swift Mailer, the Mailer class communicates with
|
||||
whichever Transport class you have chosen to use.
|
||||
|
||||
Each recipient in the message should either be accepted or rejected by the
|
||||
Transport. For example, if the domain name on the email address is not
|
||||
reachable the SMTP Transport may reject the address because it cannot process
|
||||
it. ``send()`` will return an integer indicating the number of accepted
|
||||
recipients.
|
||||
|
||||
.. note::
|
||||
|
||||
It's possible to find out which recipients were rejected -- we'll cover that
|
||||
later in this chapter.
|
||||
|
||||
Using the ``send()`` Method
|
||||
...........................
|
||||
|
||||
The ``send()`` method of the ``Swift_Mailer`` class sends a message using
|
||||
exactly the same logic as your Desktop mail client would use. Just pass it a
|
||||
Message and get a result.
|
||||
|
||||
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::
|
||||
|
||||
// Create the Transport
|
||||
$transport = new Swift_SmtpTransport('localhost', 25);
|
||||
|
||||
// Create the Mailer using your created Transport
|
||||
$mailer = new Swift_Mailer($transport);
|
||||
|
||||
// Create a message
|
||||
$message = (new Swift_Message('Wonderful Subject'))
|
||||
->setFrom(['john@doe.com' => 'John Doe'])
|
||||
->setTo(['receiver@domain.org', 'other@domain.org' => 'A name'])
|
||||
->setBody('Here is the message itself')
|
||||
;
|
||||
|
||||
// Send the message
|
||||
$numSent = $mailer->send($message);
|
||||
|
||||
printf("Sent %d messages\n", $numSent);
|
||||
|
||||
/* Note that often that only the boolean equivalent of the
|
||||
return value is of concern (zero indicates FALSE)
|
||||
|
||||
if ($mailer->send($message))
|
||||
{
|
||||
echo "Sent\n";
|
||||
}
|
||||
else
|
||||
{
|
||||
echo "Failed\n";
|
||||
}
|
||||
|
||||
*/
|
||||
|
||||
Sending Emails in Batch
|
||||
.......................
|
||||
|
||||
If you want to send a separate message to each recipient so that only their own
|
||||
address shows up in the ``To:`` field, follow the following recipe:
|
||||
|
||||
* Create a Transport from one of the provided Transports --
|
||||
``Swift_SmtpTransport``, ``Swift_SendmailTransport``,
|
||||
or one of the aggregate Transports.
|
||||
|
||||
* Create an instance of the ``Swift_Mailer`` class, using the Transport as
|
||||
it's constructor parameter.
|
||||
|
||||
* Create a Message.
|
||||
|
||||
* Iterate over the recipients and send message via the ``send()`` method on
|
||||
the Mailer object.
|
||||
|
||||
Each recipient of the messages receives a different copy with only their own
|
||||
email address on the ``To:`` field.
|
||||
|
||||
Make sure to add only valid email addresses as recipients. If you try to add an
|
||||
invalid email address with ``setTo()``, ``setCc()`` or ``setBcc()``, Swift
|
||||
Mailer will throw a ``Swift_RfcComplianceException``.
|
||||
|
||||
If you add recipients automatically based on a data source that may contain
|
||||
invalid email addresses, you can prevent possible exceptions by validating the
|
||||
addresses using ``Egulias\EmailValidator\EmailValidator`` (a dependency that is
|
||||
installed with Swift Mailer) and only adding addresses that validate. Another
|
||||
way would be to wrap your ``setTo()``, ``setCc()`` and ``setBcc()`` calls in a
|
||||
try-catch block and handle the ``Swift_RfcComplianceException`` in the catch
|
||||
block.
|
||||
|
||||
Handling invalid addresses properly is especially important when sending emails
|
||||
in large batches since a single invalid address might cause an unhandled
|
||||
exception and stop the execution or your script early.
|
||||
|
||||
.. note::
|
||||
|
||||
In the following example, two emails are sent. One to each of
|
||||
``receiver@domain.org`` and ``other@domain.org``. These recipients will
|
||||
not be aware of each other::
|
||||
|
||||
// Create the Transport
|
||||
$transport = new Swift_SmtpTransport('localhost', 25);
|
||||
|
||||
// Create the Mailer using your created Transport
|
||||
$mailer = new Swift_Mailer($transport);
|
||||
|
||||
// Create a message
|
||||
$message = (new Swift_Message('Wonderful Subject'))
|
||||
->setFrom(['john@doe.com' => 'John Doe'])
|
||||
->setBody('Here is the message itself')
|
||||
;
|
||||
|
||||
// Send the message
|
||||
$failedRecipients = [];
|
||||
$numSent = 0;
|
||||
$to = ['receiver@domain.org', 'other@domain.org' => 'A name'];
|
||||
|
||||
foreach ($to as $address => $name)
|
||||
{
|
||||
if (is_int($address)) {
|
||||
$message->setTo($name);
|
||||
} else {
|
||||
$message->setTo([$address => $name]);
|
||||
}
|
||||
|
||||
$numSent += $mailer->send($message, $failedRecipients);
|
||||
}
|
||||
|
||||
printf("Sent %d messages\n", $numSent);
|
||||
|
||||
Finding out Rejected Addresses
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
It's possible to get a list of addresses that were rejected by the Transport by
|
||||
using a by-reference parameter to ``send()``.
|
||||
|
||||
As Swift Mailer attempts to send the message to each address given to it, if a
|
||||
recipient is rejected it will be added to the array. You can pass an existing
|
||||
array, otherwise one will be created by-reference.
|
||||
|
||||
Collecting the list of recipients that were rejected can be useful in
|
||||
circumstances where you need to "prune" a mailing list for example when some
|
||||
addresses cannot be delivered to.
|
||||
|
||||
Getting Failures By-reference
|
||||
.............................
|
||||
|
||||
Collecting delivery failures by-reference with the ``send()`` method is as
|
||||
simple as passing a variable name to the method call::
|
||||
|
||||
$mailer = new Swift_Mailer( ... );
|
||||
|
||||
$message = (new Swift_Message( ... ))
|
||||
->setFrom( ... )
|
||||
->setTo([
|
||||
'receiver@bad-domain.org' => 'Receiver Name',
|
||||
'other@domain.org' => 'A name',
|
||||
'other-receiver@bad-domain.org' => 'Other Name'
|
||||
))
|
||||
->setBody( ... )
|
||||
;
|
||||
|
||||
// Pass a variable name to the send() method
|
||||
if (!$mailer->send($message, $failures))
|
||||
{
|
||||
echo "Failures:";
|
||||
print_r($failures);
|
||||
}
|
||||
|
||||
/*
|
||||
Failures:
|
||||
Array (
|
||||
0 => receiver@bad-domain.org,
|
||||
1 => other-receiver@bad-domain.org
|
||||
)
|
||||
*/
|
||||
|
||||
If the Transport rejects any of the recipients, the culprit addresses will be
|
||||
added to the array provided by-reference.
|
||||
|
||||
.. note::
|
||||
|
||||
If the variable name does not yet exist, it will be initialized as an
|
||||
empty array and then failures will be added to that array. If the variable
|
||||
already exists it will be type-cast to an array and failures will be added
|
||||
to it.
|
||||
|
||||
.. _Mailcatcher: https://mailcatcher.me/
|
Binary file not shown.
@ -6,18 +6,25 @@ Put your custom CSS in this file.
|
||||
|
||||
/* sidebar big lower portion */
|
||||
#sidebar {
|
||||
background-color: #262c31;
|
||||
/*background-color: #262c31;*/
|
||||
/*background-color: #131114;*/
|
||||
/*background-color: #34233a;*/
|
||||
background-color: #2e2333;
|
||||
}
|
||||
|
||||
/* sidebar top portion */
|
||||
#sidebar #header {
|
||||
background-color: #111314;
|
||||
/*background-color: #111314;*/
|
||||
/*background-color: #1e1321;*/
|
||||
background-color: #111111;
|
||||
}
|
||||
|
||||
/* search box in sidebar */
|
||||
#sidebar #header .searchbox {
|
||||
background: #262c31;
|
||||
border-color: #530e64;
|
||||
/*background: #262c31;*/
|
||||
background: #222222;
|
||||
/*border-color: #530e64;*/
|
||||
border-color: #2e2333;
|
||||
border-radius: 0px;
|
||||
border-width: 2px;
|
||||
}
|
||||
@ -38,6 +45,71 @@ Put your custom CSS in this file.
|
||||
opacity: 1; /* something firefox fix */
|
||||
}
|
||||
|
||||
/* full content */
|
||||
body {
|
||||
background: #ff0000;
|
||||
background: #111111;
|
||||
color: #dddddd;
|
||||
}
|
||||
|
||||
/* code blocks */
|
||||
pre {
|
||||
background: #222222;
|
||||
border: 1px solid #555555;
|
||||
}
|
||||
pre code {
|
||||
/*color: #b51c42;*/
|
||||
color: #c897d8;
|
||||
/* this padding fixes indent on first line for codeblocks */
|
||||
padding: 0;
|
||||
}
|
||||
pre .copy-to-clipboard {
|
||||
background-color: #111111;
|
||||
/*
|
||||
to revert the fix for "copy" button
|
||||
margin-top: 0;
|
||||
*/
|
||||
}
|
||||
pre .copy-to-clipboard:hover {
|
||||
background-color: #333333;
|
||||
}
|
||||
|
||||
/* inline code */
|
||||
code {
|
||||
/*color: #b51c42;*/
|
||||
color: #c897d8;
|
||||
background: #222222;
|
||||
}
|
||||
.copy-to-clipboard {
|
||||
background-color: #111111;
|
||||
background-image: url(../images/clippy-white.svg);
|
||||
/*
|
||||
makes "copy" button fit slightly better imo
|
||||
FIXME this breaks chromium
|
||||
margin-top: .2rem;
|
||||
*/
|
||||
}
|
||||
.copy-to-clipboard:hover {
|
||||
background-color: #333333;
|
||||
}
|
||||
|
||||
/* Sidebar topics */
|
||||
#sidebar ul.topics > li.parent, #sidebar ul.topics > li.active {
|
||||
/*background: #322535;*/
|
||||
/*background: #241e26;*/
|
||||
background: #252226;
|
||||
}
|
||||
|
||||
/* Sidebar currently selected main topic */
|
||||
#sidebar ul li.active > a {
|
||||
background: #111111;
|
||||
color: #dddddd !important;
|
||||
}
|
||||
|
||||
/* HACK hide checkmark icons */
|
||||
.fa.fa-check.read-icon {
|
||||
visibility: hidden;
|
||||
}
|
||||
|
||||
textarea:focus, input[type="email"]:focus, input[type="number"]:focus, input[type="password"]:focus, input[type="search"]:focus, input[type="tel"]:focus, input[type="text"]:focus, input[type="url"]:focus, input[type="color"]:focus, input[type="date"]:focus, input[type="datetime"]:focus, input[type="datetime-local"]:focus, input[type="month"]:focus, input[type="time"]:focus, input[type="week"]:focus, select[multiple="multiple"]:focus {
|
||||
box-shadow: inset 0 1px 3px rgba(0, 0, 0, 0.06), 0 0 5px rgba(164, 124, 178, 0.7);
|
||||
}
|
||||
|
3
themes/learn2/images/clippy-white.svg
Normal file
3
themes/learn2/images/clippy-white.svg
Normal file
@ -0,0 +1,3 @@
|
||||
<svg height="1024" width="896" xmlns="http://www.w3.org/2000/svg">
|
||||
<path style="fill:#dddddd" d="M128 768h256v64H128v-64z m320-384H128v64h320v-64z m128 192V448L384 640l192 192V704h320V576H576z m-288-64H128v64h160v-64zM128 704h160v-64H128v64z m576 64h64v128c-1 18-7 33-19 45s-27 18-45 19H64c-35 0-64-29-64-64V192c0-35 29-64 64-64h192C256 57 313 0 384 0s128 57 128 128h192c35 0 64 29 64 64v320h-64V320H64v576h640V768zM128 256h512c0-35-29-64-64-64h-64c-35 0-64-29-64-64s-29-64-64-64-64 29-64 64-29 64-64 64h-64c-35 0-64 29-64 64z" />
|
||||
</svg>
|
After Width: | Height: | Size: 540 B |
Loading…
Reference in New Issue
Block a user