Skip to content

Commit

Permalink
Moving the email guide to the top level
Browse files Browse the repository at this point in the history
  • Loading branch information
weaverryan committed Jul 14, 2016
1 parent 3918ee8 commit 109895f
Showing 3 changed files with 161 additions and 172 deletions.
4 changes: 2 additions & 2 deletions _build/redirection_map
Original file line number Diff line number Diff line change
@@ -7,7 +7,7 @@
/cookbook/doctrine/mongodb /bundles/DoctrineMongoDBBundle/index
/cookbook/form/dynamic_form_generation /cookbook/form/dynamic_form_modification
/cookbook/form/simple_signup_form_with_mongodb /bundles/DoctrineMongoDBBundle/form
/cookbook/email /cookbook/email/email
/cookbook/email /email
/cookbook/gmail /cookbook/email/gmail
/cookbook/console /components/console
/cookbook/tools/autoloader /components/class_loader
@@ -131,7 +131,7 @@
/cookbook/doctrine/reverse_engineering /doctrine/reverse_engineering
/cookbook/email/cloud /email/cloud
/cookbook/email/dev_environment /email/dev_environment
/cookbook/email/email /email/email
/cookbook/email/email /email
/cookbook/email/gmail /email/gmail
/cookbook/email/spool /email/spool
/cookbook/email/testing /email/testing
161 changes: 159 additions & 2 deletions email.rst
Original file line number Diff line number Diff line change
@@ -1,8 +1,165 @@
Email
=====
.. index::
single: Emails

How to Send an Email
====================

Sending emails is a classic task for any web application and one that has
special complications and potential pitfalls. Instead of recreating the wheel,
one solution to send emails is to use the SwiftmailerBundle, which leverages
the power of the `Swift Mailer`_ library. This bundle comes with the Symfony
Standard Edition.

.. _swift-mailer-configuration:

Configuration
-------------

To use Swift Mailer, you'll need to configure it for your mail server.

.. tip::

Instead of setting up/using your own mail server, you may want to use
a hosted mail provider such as `Mandrill`_, `SendGrid`_, `Amazon SES`_
or others. These give you an SMTP server, username and password (sometimes
called keys) that can be used with the Swift Mailer configuration.

In a standard Symfony installation, some ``swiftmailer`` configuration is
already included:

.. configuration-block::

.. code-block:: yaml
# app/config/config.yml
swiftmailer:
transport: '%mailer_transport%'
host: '%mailer_host%'
username: '%mailer_user%'
password: '%mailer_password%'
.. code-block:: xml
<!-- app/config/config.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:swiftmailer="http://symfony.com/schema/dic/swiftmailer"
xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/swiftmailer http://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd">
<swiftmailer:config
transport="%mailer_transport%"
host="%mailer_host%"
username="%mailer_user%"
password="%mailer_password%"
/>
</container>
.. code-block:: php
// app/config/config.php
$container->loadFromExtension('swiftmailer', array(
'transport' => "%mailer_transport%",
'host' => "%mailer_host%",
'username' => "%mailer_user%",
'password' => "%mailer_password%",
));
These values (e.g. ``%mailer_transport%``), are reading from the parameters
that are set in the :ref:`parameters.yml <config-parameters.yml>` file. You
can modify the values in that file, or set the values directly here.

The following configuration attributes are available:

* ``transport`` (``smtp``, ``mail``, ``sendmail``, or ``gmail``)
* ``username``
* ``password``
* ``host``
* ``port``
* ``encryption`` (``tls``, or ``ssl``)
* ``auth_mode`` (``plain``, ``login``, or ``cram-md5``)
* ``spool``

* ``type`` (how to queue the messages, ``file`` or ``memory`` is supported, see :doc:`/email/spool`)
* ``path`` (where to store the messages)
* ``delivery_address`` (an email address where to send ALL emails)
* ``disable_delivery`` (set to true to disable delivery completely)

Sending Emails
--------------

The Swift Mailer library works by creating, configuring and then sending
``Swift_Message`` objects. The "mailer" is responsible for the actual delivery
of the message and is accessible via the ``mailer`` service. Overall, sending
an email is pretty straightforward::

public function indexAction($name)
{
$message = \Swift_Message::newInstance()
->setSubject('Hello Email')
->setFrom('send@example.com')
->setTo('recipient@example.com')
->setBody(
$this->renderView(
// app/Resources/views/Emails/registration.html.twig
'Emails/registration.html.twig',
array('name' => $name)
),
'text/html'
)
/*
* If you also want to include a plaintext version of the message
->addPart(
$this->renderView(
'Emails/registration.txt.twig',
array('name' => $name)
),
'text/plain'
)
*/
;
$this->get('mailer')->send($message);

return $this->render(...);
}

To keep things decoupled, the email body has been stored in a template and
rendered with the ``renderView()`` method. The ``registration.html.twig``
template might look something like this:

.. code-block:: html+jinja

{# app/Resources/views/Emails/registration.html.twig #}
<h3>You did it! You registered!</h3>

Hi {{ name }}! You're successfully registered.

{# example, assuming you have a route named "login" #}
To login, go to: <a href="{{ url('login') }}">...</a>.

Thanks!

{# Makes an absolute URL to the /images/logo.png file #}
<img src="{{ absolute_url(asset('images/logo.png')) }}">

.. versionadded:: 2.7
The ``absolute_url()`` function was introduced in Symfony 2.7. Prior
to 2.7, the ``asset()`` function has an argument to enable returning
an absolute URL.

The ``$message`` object supports many more options, such as including attachments,
adding HTML content, and much more. Fortunately, Swift Mailer covers the topic
of `Creating Messages`_ in great detail in its documentation.

.. toctree::
:maxdepth: 1
:glob:

email/*

.. _`Swift Mailer`: http://swiftmailer.org/
.. _`Creating Messages`: http://swiftmailer.org/docs/messages.html
.. _`Mandrill`: https://mandrill.com/
.. _`SendGrid`: https://sendgrid.com/
.. _`Amazon SES`: http://aws.amazon.com/ses/
168 changes: 0 additions & 168 deletions email/email.rst

This file was deleted.

0 comments on commit 109895f

Please sign in to comment.