minor #12495 [Mailer] Move to the new DSN format (fabpot, javiereguiluz, tucksaun)

This PR was merged into the 4.4 branch.

Discussion
----------

[Mailer] Move to the new DSN format

Documents symfony/symfony#33424

Cherry-picking #12258 that should have target 4.4 and also add a missing DSN update.

Commits
-------

a2c607b [Mailer] Move remaining DSN to new format
ca56502 Minor tweaks
be392bc Move to the new DSN format for Mailer

Author: javiereguiluz

components/mailer.rst

@@ -85,19 +85,35 @@ DSN::
     $transport = Transport::fromDsn($dsn);
 
 Where ``$dsn`` depends on the provider you want to use. For plain SMTP, use
-``smtp://user:pass@example.com`` or ``smtp://sendmail`` to use the ``sendmail``
-binary. For third-party providers, refers to the following table:
-
-==================== ================================== ================================== ================================
- Provider             SMTP                               HTTP                               API
-==================== ================================== ================================== ================================
- Amazon SES           smtp://ACCESS_KEY:SECRET_KEY@ses   http://ACCESS_KEY:SECRET_KEY@ses   api://ACCESS_KEY:SECRET_KEY@ses
- Google Gmail         smtp://USERNAME:PASSWORD@gmail     n/a                                n/a
- Mailchimp Mandrill   smtp://USERNAME:PASSWORD@mandrill  http://KEY@mandrill                api://KEY@mandrill
- Mailgun              smtp://USERNAME:PASSWORD@mailgun   http://KEY:DOMAIN@mailgun          api://KEY:DOMAIN@mailgun
- Postmark             smtp://ID:ID@postmark              n/a                                api://KEY@postmark
- Sendgrid             smtp://apikey:KEY@sendgrid         n/a                                api://KEY@sendgrid
-==================== ================================== ================================== ================================
+``smtp://user:pass@example.com`` or ``sendmail+smtp://default`` to use the
+``sendmail`` binary. To disable the transport, use ``null://null``.
+
+For third-party providers, refer to the following table:
+
+==================== ========================================== =========================================== ========================================
+ Provider             SMTP                                       HTTP                                        API
+==================== ========================================== =========================================== ========================================
+ Amazon SES           ses+smtp://ACCESS_KEY:SECRET_KEY@default   ses+https://ACCESS_KEY:SECRET_KEY@default   ses+api://ACCESS_KEY:SECRET_KEY@default
+ Google Gmail         gmail+smtp://USERNAME:PASSWORD@default     n/a                                         n/a
+ Mailchimp Mandrill   mandrill+smtp://USERNAME:PASSWORD@default  mandrill+https://KEY@default                mandrill+api://KEY@default
+ Mailgun              mailgun+smtp://USERNAME:PASSWORD@default   mailgun+https://KEY:DOMAIN@default          mailgun+api://KEY:DOMAIN@default
+ Postmark             postmark+smtp://ID:ID@default              n/a                                         postmark+api://KEY@default
+ Sendgrid             sendgrid+smtp://apikey:KEY@default         n/a                                         sendgrid+api://KEY@default
+==================== ========================================== =========================================== ========================================
+
+Instead of choosing a specific protocol, you can also let Symfony pick the
+best one by omitting it from the scheme: for instance, ``mailgun://KEY:DOMAIN@default``
+is equivalent to ``mailgun+https://KEY:DOMAIN@default``.
+
+If you want to override the default host for a provider (to debug an issue using
+a service like ``requestbin.com``), change ``default`` by your host:
+
+.. code-block:: bash
+
+    mailgun+https://KEY:DOMAIN@example.com
+    mailgun+https://KEY:DOMAIN@example.com:99
+
+Note that the protocol is *always* HTTPs and cannot be changed.
 
 High Availability
 -----------------
@@ -108,7 +124,7 @@ to ensure that emails are sent even if one mailer server fails .
 A failover transport is configured with two or more transports and the
 ``failover`` keyword::
 
-    $dsn = 'failover(api://id@postmark smtp://key@sendgrid)';
+    $dsn = 'failover(postmark+api://ID@default sendgrid+smtp://KEY@default)';
 
 The mailer will start using the first transport. If the sending fails, the
 mailer won't retry it with the other transports, but it will switch to the next
@@ -123,7 +139,7 @@ to distribute the mailing workload across multiple transports .
 A round-robin transport is configured with two or more transports and the
 ``roundrobin`` keyword::
 
-    $dsn = 'roundrobin(api://id@postmark smtp://key@sendgrid)'
+    $dsn = 'roundrobin(postmark+api://ID@default sendgrid+smtp://KEY@default)'
 
 The mailer will start using the first transport and if it fails, it will retry
 the same delivery with the next transports until one of them succeeds (or until

mailer.rst

@@ -64,21 +64,28 @@ You'll now have a new line in your ``.env`` file that you can uncomment:
 
     # .env
     SENDGRID_KEY=
-    MAILER_DSN=smtp://$SENDGRID_KEY@sendgrid
+    MAILER_DSN=sendgrid://$SENDGRID_KEY@default
 
-The ``MAILER_DSN`` isn't a *real* SMTP address: it's a simple format that offloads
-most of the configuration work to mailer. The ``@sendgrid`` part of the address
-activates the SendGrid mailer library that you just installed, which knows all
-about how to deliver messages to SendGrid.
+The ``MAILER_DSN`` isn't a *real* address: it's a simple format that offloads
+most of the configuration work to mailer. The ``sendgrid`` scheme activates the
+SendGrid provider that you just installed, which knows all about how to deliver
+messages to SendGrid.
 
 The *only* part you need to change is to set ``SENDGRID_KEY`` to your key (in
 ``.env`` or ``.env.local``).
 
-Each transport will have different environment variables that the library will use
-to configure the *actual* address and authentication for delivery. Some also have
-options that can be configured with query parameters on end of the ``MAILER_DSN`` -
-like ``?region=`` for Amazon SES. Some transports support sending via ``http``
-or ``smtp`` - both work the same, but ``http`` is recommended when available.
+Each provider has different environment variables that the Mailer uses to
+configure the *actual* protocol, address and authentication for delivery. Some
+also have options that can be configured with query parameters at the end of the
+``MAILER_DSN`` - like ``?region=`` for Amazon SES. Some providers support
+sending via ``http``, ``api`` or ``smtp``. Symfony chooses the best available
+transport, but you can force to use one:
+
+.. code-block:: bash
+
+    # .env
+    # force to use SMTP instead of HTTP (which is the default)
+    MAILER_DSN=sendgrid+smtp://$SENDGRID_KEY@default
 
 .. tip::
 
@@ -742,7 +749,7 @@ environment:
     # config/packages/dev/mailer.yaml
     framework:
         mailer:
-            dsn: 'smtp://null'
+            dsn: 'null://null'
 
 .. note::