minor #7152 Update Swiftmailer configuration docs (jverdeyen, javiereguiluz, xabbuh)

This PR was submitted for the master branch but it was merged into the 2.7 branch instead (closes #7152).

Discussion
----------

Update Swiftmailer configuration docs

Added `delivery_addresses` configuration.

Commits
-------

bbc673a add missing dot at the end of sentence
45cbc55 add labels for old headlines
2c97e50 delivery adresses are separate XML element nodes
daaa24a Removed the description of the deprecated `delivery_address` option
55c38a6 Removed any mention of the deprecated delivery_address option
ea508f9 Removed the mention to the deprecated delivery_address option
56f6f53 Fixed a minor syntax issue
2f58823 Fixed a minor syntax issue
660aaa1 Update Swiftmailer configuration docs

Author: xabbuh

email.rst

@@ -83,7 +83,7 @@ The following configuration attributes are available:
 
   * ``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)
+* ``delivery_addresses`` (an array of email addresses where to send ALL emails)
 * ``disable_delivery`` (set to true to disable delivery completely)
 
 Sending Emails

email/dev_environment.rst

@@ -53,20 +53,22 @@ will not be sent when you run tests, but will continue to be sent in the
 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:
 
-You can also choose to have all email sent to a specific address, instead
+Sending to a Specified Address(es)
+----------------------------------
+
+You can also choose to have all email sent to a specific address or a list of addresses, instead
 of the address actually specified when sending the message. This can be done
-via the ``delivery_address`` option:
+via the ``delivery_addresses`` option:
 
 .. configuration-block::
 
     .. code-block:: yaml
 
         # app/config/config_dev.yml
         swiftmailer:
-            delivery_address: 'dev@example.com'
+            delivery_addresses: ['dev@example.com']
 
     .. code-block:: xml
 
@@ -78,14 +80,16 @@ via the ``delivery_address`` option:
             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 delivery-address="dev@example.com" />
+            <swiftmailer:config>
+                <swiftmailer:delivery-address>dev@example.com</swiftmailer:delivery-address>
+            </swiftmailer:config>
         </container>
 
     .. code-block:: php
 
         // app/config/config_dev.php
         $container->loadFromExtension('swiftmailer', array(
-            'delivery_address'  => "dev@example.com",
+            'delivery_addresses' => array("dev@example.com"),
         ));
 
 Now, suppose you're sending an email to ``recipient@example.com``.
@@ -139,7 +143,7 @@ by adding the ``delivery_whitelist`` option:
 
         # app/config/config_dev.yml
         swiftmailer:
-            delivery_address: dev@example.com
+            delivery_addresses: ['dev@example.com']
             delivery_whitelist:
                # all email addresses matching these regexes will be delivered
                # like normal, as well as being sent to dev@example.com
@@ -158,19 +162,20 @@ by adding the ``delivery_whitelist`` option:
             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 delivery-address="dev@example.com">
+            <swiftmailer:config>
                 <!-- all email addresses matching these regexes will be delivered
                      like normal, as well as being sent to dev@example.com -->
                 <swiftmailer:delivery-whitelist-pattern>/@specialdomain\.com$/</swiftmailer:delivery-whitelist-pattern>
                 <swiftmailer:delivery-whitelist-pattern>/^admin@mydomain\.com$/</swiftmailer:delivery-whitelist-pattern>
+                <swiftmailer:delivery-address>dev@example.com</swiftmailer:delivery-address>
             </swiftmailer:config>
         </container>
 
     .. code-block:: php
 
         // app/config/config_dev.php
         $container->loadFromExtension('swiftmailer', array(
-            'delivery_address'  => "dev@example.com",
+            'delivery_addresses'  => array("dev@example.com"),
             'delivery_whitelist' => array(
                 // all email addresses matching these regexes will be delivered
                 // like normal, as well as being sent to dev@example.com

reference/configuration/swiftmailer.rst

@@ -32,7 +32,7 @@ Configuration
 * `antiflood`_
     * `threshold`_
     * `sleep`_
-* `delivery_address`_
+* `delivery_addresses`_
 * `delivery_whitelist`_
 * `disable_delivery`_
 * `logging`_
@@ -145,15 +145,21 @@ sleep
 Used with ``Swift_Plugins_AntiFloodPlugin``. This is the number of seconds
 to sleep for during a transport restart.
 
-delivery_address
-~~~~~~~~~~~~~~~~
+.. _delivery-address:
 
-**type**: ``string``
+delivery_addresses
+~~~~~~~~~~~~~~~~~~
+
+**type**: ``array``
+
+.. note::
+
+    In previous versions, this option was called ``delivery_address``.
 
-If set, all email messages will be sent to this address instead of being
+If set, all email messages will be sent to these addresses instead of being
 sent to their actual recipients. This is often useful when developing. For
 example, by setting this in the ``config_dev.yml`` file, you can guarantee
-that all emails sent during development go to a single account.
+that all emails sent during development go to one or more some specific accounts.
 
 This uses ``Swift_Plugins_RedirectingPlugin``. Original recipients are available
 on the ``X-Swift-To``, ``X-Swift-Cc`` and ``X-Swift-Bcc`` headers.
@@ -163,9 +169,9 @@ delivery_whitelist
 
 **type**: ``array``
 
-Used in combination with ``delivery_address``. If set, emails matching any
+Used in combination with ``delivery_address`` or ``delivery_addresses``. If set, emails matching any
 of these patterns will be delivered like normal, as well as being sent to
-``delivery_address``. For details, see the
+``delivery_address`` or ``delivery_addresses``. For details, see the
 :ref:`How to Work with Emails during Development <sending-to-a-specified-address-but-with-exceptions>`
 article.
 
@@ -207,7 +213,7 @@ Full Default Configuration
             antiflood:
                 threshold:            99
                 sleep:                0
-            delivery_address:     ~
+            delivery_addresses:   []
             disable_delivery:     ~
             logging:              '%kernel.debug%'
 
@@ -229,7 +235,6 @@ Full Default Configuration
                 encryption=""
                 auth_mode=""
                 sender_address=""
-                delivery_address=""
                 disable_delivery=""
                 logging="%kernel.debug%"
                 >