PageRenderTime 57ms CodeModel.GetById 17ms RepoModel.GetById 1ms app.codeStats 0ms

/email/dev_environment.rst

https://github.com/hhamon/symfony-docs
ReStructuredText | 252 lines | 192 code | 60 blank | 0 comment | 0 complexity | fea7a0e59abc7b7d2ddf1319bcb6a11b MD5 | raw file
Possible License(s): ISC, MPL-2.0-no-copyleft-exception
  1. .. index::
  2. single: Emails; In development
  3. How to Work with Emails during Development
  4. ==========================================
  5. When developing an application which sends email, you will often
  6. not want to actually send the email to the specified recipient during
  7. development. If you are using the SwiftmailerBundle with Symfony, you
  8. can achieve this through configuration settings without having to make
  9. any changes to your application's code at all. There are two main choices
  10. when it comes to handling email during development: (a) disabling the
  11. sending of email altogether or (b) sending all email to a specific
  12. address (with optional exceptions).
  13. Disabling Sending
  14. -----------------
  15. You can disable sending email by setting the ``disable_delivery`` option to
  16. ``true``, which is the default value used by Symfony in the ``test`` environment
  17. (email messages will continue to be sent in the other environments):
  18. .. configuration-block::
  19. .. code-block:: yaml
  20. # config/packages/test/swiftmailer.yaml
  21. swiftmailer:
  22. disable_delivery: true
  23. .. code-block:: xml
  24. <!-- config/packages/test/swiftmailer.xml -->
  25. <?xml version="1.0" encoding="UTF-8" ?>
  26. <container xmlns="http://symfony.com/schema/dic/services"
  27. xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  28. xmlns:swiftmailer="http://symfony.com/schema/dic/swiftmailer"
  29. xsi:schemaLocation="http://symfony.com/schema/dic/services
  30. https://symfony.com/schema/dic/services/services-1.0.xsd
  31. http://symfony.com/schema/dic/swiftmailer https://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd">
  32. <swiftmailer:config disable-delivery="true"/>
  33. </container>
  34. .. code-block:: php
  35. // config/packages/test/swiftmailer.php
  36. $container->loadFromExtension('swiftmailer', [
  37. 'disable_delivery' => "true",
  38. ]);
  39. .. _sending-to-a-specified-address:
  40. Sending to a Specified Address(es)
  41. ----------------------------------
  42. You can also choose to have all email sent to a specific address or a list of addresses, instead
  43. of the address actually specified when sending the message. This can be done
  44. via the ``delivery_addresses`` option:
  45. .. configuration-block::
  46. .. code-block:: yaml
  47. # config/packages/dev/swiftmailer.yaml
  48. swiftmailer:
  49. delivery_addresses: ['dev@example.com']
  50. .. code-block:: xml
  51. <!-- config/packages/dev/swiftmailer.xml -->
  52. <?xml version="1.0" encoding="UTF-8" ?>
  53. <container xmlns="http://symfony.com/schema/dic/services"
  54. xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  55. xmlns:swiftmailer="http://symfony.com/schema/dic/swiftmailer"
  56. xsi:schemaLocation="http://symfony.com/schema/dic/services
  57. https://symfony.com/schema/dic/services/services-1.0.xsd
  58. http://symfony.com/schema/dic/swiftmailer
  59. https://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd">
  60. <swiftmailer:config>
  61. <swiftmailer:delivery-address>dev@example.com</swiftmailer:delivery-address>
  62. </swiftmailer:config>
  63. </container>
  64. .. code-block:: php
  65. // config/packages/dev/swiftmailer.php
  66. $container->loadFromExtension('swiftmailer', [
  67. 'delivery_addresses' => ['dev@example.com'],
  68. ]);
  69. Now, suppose you're sending an email to ``recipient@example.com`` in a controller::
  70. public function index($name, \Swift_Mailer $mailer)
  71. {
  72. $message = (new \Swift_Message('Hello Email'))
  73. ->setFrom('send@example.com')
  74. ->setTo('recipient@example.com')
  75. ->setBody(
  76. $this->renderView(
  77. 'HelloBundle:Hello:email.txt.twig',
  78. ['name' => $name]
  79. )
  80. )
  81. ;
  82. $mailer->send($message);
  83. return $this->render(...);
  84. }
  85. In the ``dev`` environment, the email will instead be sent to ``dev@example.com``.
  86. Swift Mailer will add an extra header to the email, ``X-Swift-To``, containing
  87. the replaced address, so you can still see who it would have been sent to.
  88. .. note::
  89. In addition to the ``to`` addresses, this will also stop the email being
  90. sent to any ``CC`` and ``BCC`` addresses set for it. Swift Mailer will add
  91. additional headers to the email with the overridden addresses in them.
  92. These are ``X-Swift-Cc`` and ``X-Swift-Bcc`` for the ``CC`` and ``BCC``
  93. addresses respectively.
  94. .. _sending-to-a-specified-address-but-with-exceptions:
  95. Sending to a Specified Address but with Exceptions
  96. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  97. Suppose you want to have all email redirected to a specific address,
  98. (like in the above scenario to ``dev@example.com``). But then you may want
  99. email sent to some specific email addresses to go through after all, and
  100. not be redirected (even if it is in the dev environment). This can be done
  101. by adding the ``delivery_whitelist`` option:
  102. .. configuration-block::
  103. .. code-block:: yaml
  104. # config/packages/dev/swiftmailer.yaml
  105. swiftmailer:
  106. delivery_addresses: ['dev@example.com']
  107. delivery_whitelist:
  108. # all email addresses matching these regexes will be delivered
  109. # like normal, as well as being sent to dev@example.com
  110. - '/@specialdomain\.com$/'
  111. - '/^admin@mydomain\.com$/'
  112. .. code-block:: xml
  113. <!-- config/packages/dev/swiftmailer.xml -->
  114. <?xml version="1.0" encoding="UTF-8" ?>
  115. <container xmlns="http://symfony.com/schema/dic/services"
  116. xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  117. xmlns:swiftmailer="http://symfony.com/schema/dic/swiftmailer"
  118. xsi:schemaLocation="http://symfony.com/schema/dic/services
  119. https://symfony.com/schema/dic/services/services-1.0.xsd
  120. http://symfony.com/schema/dic/swiftmailer
  121. https://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd">
  122. <swiftmailer:config>
  123. <!-- all email addresses matching these regexes will be delivered
  124. like normal, as well as being sent to dev@example.com -->
  125. <swiftmailer:delivery-whitelist-pattern>/@specialdomain\.com$/</swiftmailer:delivery-whitelist-pattern>
  126. <swiftmailer:delivery-whitelist-pattern>/^admin@mydomain\.com$/</swiftmailer:delivery-whitelist-pattern>
  127. <swiftmailer:delivery-address>dev@example.com</swiftmailer:delivery-address>
  128. </swiftmailer:config>
  129. </container>
  130. .. code-block:: php
  131. // config/packages/dev/swiftmailer.php
  132. $container->loadFromExtension('swiftmailer', [
  133. 'delivery_addresses' => ["dev@example.com"],
  134. 'delivery_whitelist' => [
  135. // all email addresses matching these regexes will be delivered
  136. // like normal, as well as being sent to dev@example.com
  137. '/@specialdomain\.com$/',
  138. '/^admin@mydomain\.com$/',
  139. ],
  140. ]);
  141. In the above example all email messages will be redirected to ``dev@example.com``
  142. and messages sent to the ``admin@mydomain.com`` address or to any email address
  143. belonging to the domain ``specialdomain.com`` will also be delivered as normal.
  144. .. caution::
  145. The ``delivery_whitelist`` option is ignored unless the ``delivery_addresses`` option is defined.
  146. Viewing from the Web Debug Toolbar
  147. ----------------------------------
  148. You can view any email sent during a single response when you are in the
  149. ``dev`` environment using the web debug toolbar. The email icon in the toolbar
  150. will show how many emails were sent. If you click it, a report will open
  151. showing the details of the sent emails.
  152. If you're sending an email and then immediately redirecting to another page,
  153. the web debug toolbar will not display an email icon or a report on the next
  154. page.
  155. Instead, you can set the ``intercept_redirects`` option to ``true`` in the
  156. ``dev`` environment, which will cause the redirect to stop and allow you to open
  157. the report with details of the sent emails.
  158. .. configuration-block::
  159. .. code-block:: yaml
  160. # config/packages/dev/web_profiler.yaml
  161. web_profiler:
  162. intercept_redirects: true
  163. .. code-block:: xml
  164. <!-- config/packages/dev/web_profiler.xml -->
  165. <?xml version="1.0" encoding="UTF-8" ?>
  166. <container xmlns="http://symfony.com/schema/dic/services"
  167. xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  168. xmlns:webprofiler="http://symfony.com/schema/dic/webprofiler"
  169. xsi:schemaLocation="http://symfony.com/schema/dic/services
  170. https://symfony.com/schema/dic/services/services-1.0.xsd
  171. http://symfony.com/schema/dic/webprofiler
  172. https://symfony.com/schema/dic/webprofiler/webprofiler-1.0.xsd">
  173. <webprofiler:config
  174. intercept-redirects="true"
  175. />
  176. </container>
  177. .. code-block:: php
  178. // config/packages/dev/web_profiler.php
  179. $container->loadFromExtension('web_profiler', [
  180. 'intercept_redirects' => 'true',
  181. ]);
  182. .. tip::
  183. Alternatively, you can open the profiler after the redirect and search
  184. by the submit URL used on the previous request (e.g. ``/contact/handle``).
  185. The profiler's search feature allows you to load the profiler information
  186. for any past requests.
  187. .. tip::
  188. In addition to the features provided by Symfony, there are applications that
  189. can help you test emails during application development, like `MailCatcher`_
  190. and `MailHog`_.
  191. .. _`MailCatcher`: https://github.com/sj26/mailcatcher
  192. .. _`MailHog`: https://github.com/mailhog/MailHog