From bcdeeac6eabed64c28342ccaef37adb5c3e3606f Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Wed, 15 Nov 2017 13:22:59 +0100 Subject: [PATCH] Updated the email/* articles --- email/cloud.rst | 88 ++++------------------------------- email/dev_environment.rst | 47 ++++++++----------- email/gmail.rst | 97 ++------------------------------------- email/spool.rst | 36 +++++++-------- email/testing.rst | 4 +- 5 files changed, 55 insertions(+), 217 deletions(-) diff --git a/email/cloud.rst b/email/cloud.rst index d7ddbd33f3b..3166405141f 100644 --- a/email/cloud.rst +++ b/email/cloud.rst @@ -18,86 +18,18 @@ This article shows how easy it is to integrate .. note:: You can use the same technique for other mail services, as most of the - time there is nothing more to it than configuring an SMTP endpoint for - Swift Mailer. - -In the Symfony configuration, change the Swift Mailer settings ``transport``, -``host``, ``port`` and ``encryption`` according to the information provided in -the `SES console`_. Create your individual SMTP credentials in the SES console -and complete the configuration with the provided ``username`` and ``password``: - -.. configuration-block:: - - .. code-block:: yaml - - # app/config/config.yml - swiftmailer: - transport: smtp - host: email-smtp.us-east-1.amazonaws.com - port: 587 # different ports are available, see SES console - encryption: tls # TLS encryption is required - username: AWS_SES_SMTP_USERNAME # to be created in the SES console - password: AWS_SES_SMTP_PASSWORD # to be created in the SES console - - .. code-block:: xml - - - - - - - - - - .. code-block:: php - - // app/config/config.php - $container->loadFromExtension('swiftmailer', array( - 'transport' => 'smtp', - 'host' => 'email-smtp.us-east-1.amazonaws.com', - 'port' => 587, - 'encryption' => 'tls', - 'username' => 'AWS_SES_SMTP_USERNAME', - 'password' => 'AWS_SES_SMTP_PASSWORD', - )); - -The ``port`` and ``encryption`` keys are not present in the Symfony Standard -Edition configuration by default, but you can simply add them as needed. + time there is nothing more to it than configuring an SMTP endpoint. -And that's it, you're ready to start sending emails through the cloud! +Symfony's mailer uses the ``MAILER_URL`` environment variable to store the +SMTP connection parameters, including the security credentials. Get those +parameters from the `SES console`_ and update the value of ``MAILER_URL`` in +the ``.env`` file: + +.. code-block:: bash -.. tip:: - - If you are using the Symfony Standard Edition, configure the parameters in - ``parameters.yml`` and use them in your configuration files. This allows - for different Swift Mailer configurations for each installation of your - application. For instance, use Gmail during development and the cloud in - production. - - .. code-block:: yaml - - # app/config/parameters.yml - parameters: - # ... - mailer_transport: smtp - mailer_host: email-smtp.us-east-1.amazonaws.com - mailer_port: 587 # different ports are available, see SES console - mailer_encryption: tls # TLS encryption is required - mailer_user: AWS_SES_SMTP_USERNAME # to be created in the SES console - mailer_password: AWS_SES_SMTP_PASSWORD # to be created in the SES console + MAILER_URL=smtp://email-smtp.us-east-1.amazonaws.com:587?encryption=tls&username=YOUR_SES_USERNAME&password=YOUR_SES_PASSWORD + +And that's it, you're ready to start sending emails through the cloud! .. note:: diff --git a/email/dev_environment.rst b/email/dev_environment.rst index ebb0a46024f..ce659a533aa 100644 --- a/email/dev_environment.rst +++ b/email/dev_environment.rst @@ -6,7 +6,7 @@ How to Work with Emails during Development When developing an application which sends email, you will often not want to actually send the email to the specified recipient during -development. If you are using the SwiftmailerBundle with Symfony, you +development. If you are using the default Symfony mailer, you can easily achieve this through configuration settings without having to make any changes to your application's code at all. There are two main choices when it comes to handling email during development: (a) disabling the @@ -16,23 +16,21 @@ address (with optional exceptions). Disabling Sending ----------------- -You can disable sending email by setting the ``disable_delivery`` option -to ``true``. This is the default in the ``test`` environment in the Standard -distribution. If you do this in the ``test`` specific config then email -will not be sent when you run tests, but will continue to be sent in the -``prod`` and ``dev`` environments: +You can disable sending email by setting the ``disable_delivery`` option to +``true``, which is the default value used by Symfony in the ``test`` environment +(email messages will continue to be sent in the other environments): .. configuration-block:: .. code-block:: yaml - # app/config/config_test.yml + # config/packages/test/swiftmailer.yaml swiftmailer: disable_delivery: true .. code-block:: xml - + loadFromExtension('swiftmailer', array( 'disable_delivery' => "true", )); -If you'd also like to disable deliver in the ``dev`` environment, simply -add this same configuration to the ``config_dev.yml`` file. - .. _sending-to-a-specified-address: Sending to a Specified Address(es) @@ -67,13 +62,13 @@ via the ``delivery_addresses`` option: .. code-block:: yaml - # app/config/config_dev.yml + # config/packages/dev/swiftmailer.yaml swiftmailer: delivery_addresses: ['dev@example.com'] .. code-block:: xml - + loadFromExtension('swiftmailer', array( 'delivery_addresses' => array("dev@example.com"), )); -Now, suppose you're sending an email to ``recipient@example.com``. - -.. code-block:: php +Now, suppose you're sending an email to ``recipient@example.com`` in a controller:: - public function indexAction($name, \Swift_Mailer $mailer) + public function index($name, \Swift_Mailer $mailer) { $message = (new \Swift_Message('Hello Email')) ->setFrom('send@example.com') @@ -143,7 +136,7 @@ by adding the ``delivery_whitelist`` option: .. code-block:: yaml - # app/config/config_dev.yml + # config/packages/dev/swiftmailer.yaml swiftmailer: delivery_addresses: ['dev@example.com'] delivery_whitelist: @@ -154,7 +147,7 @@ by adding the ``delivery_whitelist`` option: .. code-block:: xml - + loadFromExtension('swiftmailer', array( 'delivery_addresses' => array("dev@example.com"), 'delivery_whitelist' => array( @@ -207,20 +200,20 @@ the web debug toolbar will not display an email icon or a report on the next page. Instead, you can set the ``intercept_redirects`` option to ``true`` in the -``config_dev.yml`` file, which will cause the redirect to stop and allow -you to open the report with details of the sent emails. +``dev`` environment, which will cause the redirect to stop and allow you to open +the report with details of the sent emails. .. configuration-block:: .. code-block:: yaml - # app/config/config_dev.yml + # config/packages/dev/swiftmailer.yaml web_profiler: intercept_redirects: true .. code-block:: xml - + loadFromExtension('web_profiler', array( 'intercept_redirects' => 'true', )); diff --git a/email/gmail.rst b/email/gmail.rst index e34604bae0a..a8d456edaa4 100644 --- a/email/gmail.rst +++ b/email/gmail.rst @@ -5,102 +5,15 @@ How to Use Gmail to Send Emails =============================== During development, instead of using a regular SMTP server to send emails, you -might find using Gmail easier and more practical. The SwiftmailerBundle makes +might find using Gmail easier and more practical. The Symfony mailer makes it really easy. -In the development configuration file, change the ``transport`` setting to -``gmail`` and set the ``username`` and ``password`` to the Google credentials: +In the ``.env`` file used in your development machine, change the ``MAILER_URL`` +environment variable to this: -.. configuration-block:: +.. code-block:: bash - .. code-block:: yaml - - # app/config/config_dev.yml - swiftmailer: - transport: gmail - username: your_gmail_username - password: your_gmail_password - - .. code-block:: xml - - - - - - - - - - .. code-block:: php - - // app/config/config_dev.php - $container->loadFromExtension('swiftmailer', array( - 'transport' => 'gmail', - 'username' => 'your_gmail_username', - 'password' => 'your_gmail_password', - )); - -.. tip:: - - It's more convenient to configure these options in the ``parameters.yml`` - file: - - .. code-block:: yaml - - # app/config/parameters.yml - parameters: - # ... - mailer_user: your_gmail_username - mailer_password: your_gmail_password - - .. configuration-block:: - - .. code-block:: yaml - - # app/config/config_dev.yml - swiftmailer: - transport: gmail - username: '%mailer_user%' - password: '%mailer_password%' - - .. code-block:: xml - - - - - - - - - - .. code-block:: php - - // app/config/config_dev.php - $container->loadFromExtension('swiftmailer', array( - 'transport' => 'gmail', - 'username' => '%mailer_user%', - 'password' => '%mailer_password%', - )); + MAILER_URL=gmail://YOUR_GMAIL_USERNAME:YOUR_GMAIL_PASSWORD@localhost Redefining the Default Configuration Parameters ----------------------------------------------- diff --git a/email/spool.rst b/email/spool.rst index f7827bb8ff5..d8afa6ba88d 100644 --- a/email/spool.rst +++ b/email/spool.rst @@ -4,16 +4,16 @@ How to Spool Emails =================== -When you are using the SwiftmailerBundle to send an email from a Symfony -application, it will default to sending the email immediately. You may, however, -want to avoid the performance hit of the communication between Swift Mailer -and the email transport, which could cause the user to wait for the next -page to load while the email is sending. This can be avoided by choosing -to "spool" the emails instead of sending them directly. This means that Swift Mailer -does not attempt to send the email but instead saves the message to somewhere -such as a file. Another process can then read from the spool and take care -of sending the emails in the spool. Currently only spooling to file or memory is supported -by Swift Mailer. +The default behavior of the Symfony mailer is to send the email messages +immediately. You may, however, want to avoid the performance hit of the +communication to the email server, which could cause the user to wait for the +next page to load while the email is sending. This can be avoided by choosing to +"spool" the emails instead of sending them directly. + +This makes the mailer to not attempt to send the email message but instead save +it somewhere such as a file. Another process can then read from the spool and +take care of sending the emails in the spool. Currently only spooling to file or +memory is supported. Spool Using Memory ------------------ @@ -21,20 +21,20 @@ Spool Using Memory When you use spooling to store the emails to memory, they will get sent right before the kernel terminates. This means the email only gets sent if the whole request got executed without any unhandled exception or any errors. To configure -swiftmailer with the memory option, use the following configuration: +this spool, use the following configuration: .. configuration-block:: .. code-block:: yaml - # app/config/config.yml + # config/packages/swiftmailer.yaml swiftmailer: # ... spool: { type: memory } .. code-block:: xml - + loadFromExtension('swiftmailer', array( // ... 'spool' => array('type' => 'memory') @@ -71,7 +71,7 @@ In order to use the spool with files, use the following configuration: .. code-block:: yaml - # app/config/config.yml + # config/packages/swiftmailer.yaml swiftmailer: # ... spool: @@ -80,7 +80,7 @@ In order to use the spool with files, use the following configuration: .. code-block:: xml - + loadFromExtension('swiftmailer', array( // ... @@ -117,7 +117,7 @@ In order to use the spool with files, use the following configuration: .. code-block:: yaml - path: '%kernel.project_dir%/app/spool' + path: '%kernel.project_dir%/var/spool' Now, when your app sends an email, it will not actually be sent but instead added to the spool. Sending the messages from the spool is done separately. diff --git a/email/testing.rst b/email/testing.rst index 9e9597f5e58..477db8f5474 100644 --- a/email/testing.rst +++ b/email/testing.rst @@ -10,9 +10,9 @@ SwiftmailerBundle, which leverages the power of the `Swift Mailer`_ library. To functionally test that an email was sent, and even assert the email subject, content or any other headers, you can use :doc:`the Symfony Profiler `. -Start with an easy controller action that sends an email:: +Start with a simple controller action that sends an email:: - public function sendEmailAction($name, \Swift_Mailer $mailer) + public function sendEmail($name, \Swift_Mailer $mailer) { $message = (new \Swift_Message('Hello Email')) ->setFrom('send@example.com')