Skip to content

Commit 44b59ca

Browse files
javiereguiluzjaviereguiluz
committed
minor #87 Moving the email guide to the top level (weaverryan)
This PR was merged into the 2.7 branch. Discussion ---------- Moving the email guide to the top level Fixes part of #51 Article moved without changes (though git doesn't seem to agree!). Commits ------- 109895f Moving the email guide to the top level
2 parents 00494c1 + 109895f commit 44b59ca

File tree

3 files changed

+161
-172
lines changed

3 files changed

+161
-172
lines changed

‎_build/redirection_map

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77
/cookbook/doctrine/mongodb /bundles/DoctrineMongoDBBundle/index
88
/cookbook/form/dynamic_form_generation /cookbook/form/dynamic_form_modification
99
/cookbook/form/simple_signup_form_with_mongodb /bundles/DoctrineMongoDBBundle/form
10-
/cookbook/email /cookbook/email/email
10+
/cookbook/email /email
1111
/cookbook/gmail /cookbook/email/gmail
1212
/cookbook/console /components/console
1313
/cookbook/tools/autoloader /components/class_loader
@@ -131,7 +131,7 @@
131131
/cookbook/doctrine/reverse_engineering /doctrine/reverse_engineering
132132
/cookbook/email/cloud /email/cloud
133133
/cookbook/email/dev_environment /email/dev_environment
134-
/cookbook/email/email /email/email
134+
/cookbook/email/email /email
135135
/cookbook/email/gmail /email/gmail
136136
/cookbook/email/spool /email/spool
137137
/cookbook/email/testing /email/testing

‎email.rst

Lines changed: 159 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,165 @@
1-
Email
2-
=====
1+
.. index::
2+
single: Emails
3+
4+
How to Send an Email
5+
====================
6+
7+
Sending emails is a classic task for any web application and one that has
8+
special complications and potential pitfalls. Instead of recreating the wheel,
9+
one solution to send emails is to use the SwiftmailerBundle, which leverages
10+
the power of the `Swift Mailer`_ library. This bundle comes with the Symfony
11+
Standard Edition.
12+
13+
.. _swift-mailer-configuration:
14+
15+
Configuration
16+
-------------
17+
18+
To use Swift Mailer, you'll need to configure it for your mail server.
19+
20+
.. tip::
21+
22+
Instead of setting up/using your own mail server, you may want to use
23+
a hosted mail provider such as `Mandrill`_, `SendGrid`_, `Amazon SES`_
24+
or others. These give you an SMTP server, username and password (sometimes
25+
called keys) that can be used with the Swift Mailer configuration.
26+
27+
In a standard Symfony installation, some ``swiftmailer`` configuration is
28+
already included:
29+
30+
.. configuration-block::
31+
32+
.. code-block:: yaml
33+
34+
# app/config/config.yml
35+
swiftmailer:
36+
transport: '%mailer_transport%'
37+
host: '%mailer_host%'
38+
username: '%mailer_user%'
39+
password: '%mailer_password%'
40+
41+
.. code-block:: xml
42+
43+
<!-- app/config/config.xml -->
44+
<?xml version="1.0" encoding="UTF-8" ?>
45+
<container xmlns="http://symfony.com/schema/dic/services"
46+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
47+
xmlns:swiftmailer="http://symfony.com/schema/dic/swiftmailer"
48+
xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
49+
http://symfony.com/schema/dic/swiftmailer http://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd">
50+
51+
<swiftmailer:config
52+
transport="%mailer_transport%"
53+
host="%mailer_host%"
54+
username="%mailer_user%"
55+
password="%mailer_password%"
56+
/>
57+
</container>
58+
59+
.. code-block:: php
60+
61+
// app/config/config.php
62+
$container->loadFromExtension('swiftmailer', array(
63+
'transport' => "%mailer_transport%",
64+
'host' => "%mailer_host%",
65+
'username' => "%mailer_user%",
66+
'password' => "%mailer_password%",
67+
));
68+
69+
These values (e.g. ``%mailer_transport%``), are reading from the parameters
70+
that are set in the :ref:`parameters.yml <config-parameters.yml>` file. You
71+
can modify the values in that file, or set the values directly here.
72+
73+
The following configuration attributes are available:
74+
75+
* ``transport`` (``smtp``, ``mail``, ``sendmail``, or ``gmail``)
76+
* ``username``
77+
* ``password``
78+
* ``host``
79+
* ``port``
80+
* ``encryption`` (``tls``, or ``ssl``)
81+
* ``auth_mode`` (``plain``, ``login``, or ``cram-md5``)
82+
* ``spool``
83+
84+
* ``type`` (how to queue the messages, ``file`` or ``memory`` is supported, see :doc:`/email/spool`)
85+
* ``path`` (where to store the messages)
86+
* ``delivery_address`` (an email address where to send ALL emails)
87+
* ``disable_delivery`` (set to true to disable delivery completely)
88+
89+
Sending Emails
90+
--------------
91+
92+
The Swift Mailer library works by creating, configuring and then sending
93+
``Swift_Message`` objects. The "mailer" is responsible for the actual delivery
94+
of the message and is accessible via the ``mailer`` service. Overall, sending
95+
an email is pretty straightforward::
96+
97+
public function indexAction($name)
98+
{
99+
$message = \Swift_Message::newInstance()
100+
->setSubject('Hello Email')
101+
->setFrom('send@example.com')
102+
->setTo('recipient@example.com')
103+
->setBody(
104+
$this->renderView(
105+
// app/Resources/views/Emails/registration.html.twig
106+
'Emails/registration.html.twig',
107+
array('name' => $name)
108+
),
109+
'text/html'
110+
)
111+
/*
112+
* If you also want to include a plaintext version of the message
113+
->addPart(
114+
$this->renderView(
115+
'Emails/registration.txt.twig',
116+
array('name' => $name)
117+
),
118+
'text/plain'
119+
)
120+
*/
121+
;
122+
$this->get('mailer')->send($message);
123+
124+
return $this->render(...);
125+
}
126+
127+
To keep things decoupled, the email body has been stored in a template and
128+
rendered with the ``renderView()`` method. The ``registration.html.twig``
129+
template might look something like this:
130+
131+
.. code-block:: html+jinja
132+
133+
{# app/Resources/views/Emails/registration.html.twig #}
134+
<h3>You did it! You registered!</h3>
135+
136+
Hi {{ name }}! You're successfully registered.
137+
138+
{# example, assuming you have a route named "login" #}
139+
To login, go to: <a href="{{ url('login') }}">...</a>.
140+
141+
Thanks!
142+
143+
{# Makes an absolute URL to the /images/logo.png file #}
144+
<img src="{{ absolute_url(asset('images/logo.png')) }}">
145+
146+
.. versionadded:: 2.7
147+
The ``absolute_url()`` function was introduced in Symfony 2.7. Prior
148+
to 2.7, the ``asset()`` function has an argument to enable returning
149+
an absolute URL.
150+
151+
The ``$message`` object supports many more options, such as including attachments,
152+
adding HTML content, and much more. Fortunately, Swift Mailer covers the topic
153+
of `Creating Messages`_ in great detail in its documentation.
3154

4155
.. toctree::
5156
:maxdepth: 1
6157
:glob:
7158

8159
email/*
160+
161+
.. _`Swift Mailer`: http://swiftmailer.org/
162+
.. _`Creating Messages`: http://swiftmailer.org/docs/messages.html
163+
.. _`Mandrill`: https://mandrill.com/
164+
.. _`SendGrid`: https://sendgrid.com/
165+
.. _`Amazon SES`: http://aws.amazon.com/ses/

‎email/email.rst

Lines changed: 0 additions & 168 deletions
This file was deleted.

0 commit comments

Comments
 (0)