Updated the main email article to Symfony 4/Flex

Author: javiereguiluz

email.rst

@@ -4,102 +4,57 @@
 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.
+Sending emails is a common task for any web application and one that has
+special complications and potential pitfalls. Symfony provides a mailer feature
+based on the popular `Swift Mailer`_ library via the `SwiftMailerBundle`_.
 
-.. _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.
+The Symfony mailer supports sending messages with your own mail servers as well
+as using popular email providers like `Mandrill`_, `SendGrid`_, and `Amazon SES`_.
 
-In a standard Symfony installation, some ``swiftmailer`` configuration is
-already included:
+Installation
+------------
 
-.. configuration-block::
+In applications using :doc:`Symfony Flex </setup/flex>`, execute this command to
+install and enable the mailer:
 
-    .. code-block:: yaml
+.. code-block:: terminal
 
-        # app/config/config.yml
-        swiftmailer:
-            transport: '%mailer_transport%'
-            host:      '%mailer_host%'
-            username:  '%mailer_user%'
-            password:  '%mailer_password%'
+    $ composer require mailer
 
-    .. code-block:: xml
+If your application doesn't use Symfony Flex, follow the installation
+instructions of the `SwiftMailerBundle`_.
 
-        <!-- 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
+.. _swift-mailer-configuration:
 
-        // app/config/config.php
-        $container->loadFromExtension('swiftmailer', array(
-            'transport'  => "%mailer_transport%",
-            'host'       => "%mailer_host%",
-            'username'   => "%mailer_user%",
-            'password'   => "%mailer_password%",
-        ));
+Configuration
+-------------
 
-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 ``config/packages/swiftmailer.yaml`` file created when installing the mailer
+provides all the initial config needed to make it work, except the parameters
+required to connect to the mail server. Those parameters are defined in the
+``MAILER_URL`` environment variable in the ``.env`` file:
 
-The following configuration attributes are available:
+.. code-block:: bash
 
-* ``transport`` (``smtp``, ``mail``, ``sendmail``, or ``gmail``)
-* ``username``
-* ``password``
-* ``host``
-* ``port``
-* ``encryption`` (``tls``, or ``ssl``)
-* ``auth_mode`` (``plain``, ``login``, or ``cram-md5``)
-* ``spool``
+    # use this to disable the email delivery
+    MAILER_URL=null://localhost
 
-  * ``type`` (how to queue the messages, ``file`` or ``memory`` is supported, see :doc:`/email/spool`)
-  * ``path`` (where to store the messages)
-* ``delivery_addresses`` (an array of email addresses where to send ALL emails)
-* ``disable_delivery`` (set to true to disable delivery completely)
+    # use this to send emails via Gmail (don't use this in production)
+    MAILER_URL=gmail://username:password@localhost
 
-.. caution::
+    # use this to configure a traditional SMTP server
+    MAILER_URL=smtp://localhost:25?encryption=ssl&auth_mode=login&username=&password=
 
-    Starting from SwiftMailer 5.4.5, the ``mail`` transport is deprecated
-    and will be removed in version 6. Consider using another transport like
-    ``smtp``, ``sendmail`` or ``gmail``.
+Refer to the :doc:`SwiftMailer configuration reference </reference/configuration/swiftmailer.yml>`
+for the detailed explanation of all the available config options.
 
 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::
+of the message and is accessible via the ``Swift_Mailer`` service. Overall,
+sending an email is pretty straightforward::
 
     public function indexAction($name, \Swift_Mailer $mailer)
     {
@@ -108,8 +63,8 @@ an email is pretty straightforward::
             ->setTo('recipient@example.com')
             ->setBody(
                 $this->renderView(
-                    // templates/Emails/registration.html.twig
-                    'Emails/registration.html.twig',
+                    // templates/emails/registration.html.twig
+                    'emails/registration.html.twig',
                     array('name' => $name)
                 ),
                 'text/html'
@@ -118,7 +73,7 @@ an email is pretty straightforward::
              * If you also want to include a plaintext version of the message
             ->addPart(
                 $this->renderView(
-                    'Emails/registration.txt.twig',
+                    'emails/registration.txt.twig',
                     array('name' => $name)
                 ),
                 'text/plain'
@@ -128,9 +83,6 @@ an email is pretty straightforward::
 
         $mailer->send($message);
 
-        // or, you can also fetch the mailer service this way
-        // $this->get('mailer')->send($message);
-
         return $this->render(...);
     }
 
@@ -140,7 +92,7 @@ template might look something like this:
 
 .. code-block:: html+jinja
 
-    {# templates/Emails/registration.html.twig #}
+    {# templates/emails/registration.html.twig #}
     <h3>You did it! You registered!</h3>
 
     Hi {{ name }}! You're successfully registered.
@@ -154,19 +106,23 @@ template might look something like this:
     <img src="{{ absolute_url(asset('images/logo.png')) }}">
 
 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.
+adding HTML content, and much more. Refer to the `Creating Messages`_ section
+of the Swift Mailer documentation for more details.
 
 Learn more
 ----------
 
 .. toctree::
     :maxdepth: 1
-    :glob:
 
-    email/*
+    email/dev_environment
+    email/gmail
+    email/cloud
+    email/spool
+    email/testing
 
 .. _`Swift Mailer`: http://swiftmailer.org/
+.. _`SwiftMailerBundle`: https://github.com/symfony/swiftmailer-bundle
 .. _`Creating Messages`: http://swiftmailer.org/docs/messages.html
 .. _`Mandrill`: https://mandrill.com/
 .. _`SendGrid`: https://sendgrid.com/