From e2c89df9012faeab59c85decb7b714e3c2361b96 Mon Sep 17 00:00:00 2001 From: Hari KT Date: Thu, 30 May 2019 13:30:23 +0530 Subject: [PATCH 1/8] Initial mailer component docs --- components/mailer.rst | 125 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 123 insertions(+), 2 deletions(-) diff --git a/components/mailer.rst b/components/mailer.rst index b36b44efb3d..054deeb01f3 100644 --- a/components/mailer.rst +++ b/components/mailer.rst @@ -16,8 +16,129 @@ Installation .. include:: /components/require_autoload.rst.inc + +Introduction +------------ + + Usage ----- -We're currently working on the documentation of this component that was just -added to Symfony. We'll publish it in a few days. + use Symfony\Component\Mailer\Mailer; + use Symfony\Component\Mailer\Transport\Smtp\SmtpTransport; + + $transport = new SmtpTransport('localhost'); + $mailer = new Mailer($transport); + $mailer->send($email); + +Refer :doc:`Mime component ` how to create `$email` object. + + +Transport +--------- + +By default, the only transport available in the mailer component is Smtp. +Below is the list of other popular providers with built in support. +- Amazon SES : symfony/amazon-mailer +- Google Gmail : symfony/google-mailer +- Mandrill : symfony/mailchimp-mailer +- Mailgun : symfony/mailgun-mailer +- Postmark : symfony/postmark-mailer +- Sendgrid : symfony/sendgrid-mailer + +For example to use google's gmail as a transport you need to install symfony/google-mailer. + +.. code-block:: terminal + + $ composer require symfony/google-mailer + +.. include:: /components/require_autoload.rst.inc + + + use Symfony\Component\Mailer\Bridge\Google\Smtp\GmailTransport; + + $transport = new GmailTransport('user', 'pass'); + $transport->send($email); + +Use a Dsn +--------- + +The mailer component provides a convenient way to create transport object from dsn string. + + use Symfony\Component\Mailer\Transport; + + $transport = Transport::fromDsn($dsn); + +Where `$dns` as one of the form below. +- smtp://user:pass@gmail +- smtp://key@sendgrid +- smtp://null +- smtp://user:pass@mailgun +- http://key:domain@mailgun +- api://id@postmark + +This provides a unified behaviour across all providers. +Easily switch from SMTP in dev to a "real" provider in production with same API. + +Failover transport +------------------ + +You can create failover transport with the help of `||` operator. + +Eg : + + $dsn = 'api://id@postmark || smtp://key@sendgrid'; + +So if it fails at one transport, the mailer will attempt to send through the other transport. + +RoundRobin +---------- + +If you want to send mails via multiple transports, you can use the `&&` operator between the transports. + +Eg : + + $dsn = 'api://id@postmark && smtp://key@sendgrid' + + +Async +----- + +If you want to use the async functionality you need to install `messenger` component. +By default, `$bus` is null and if it is not configured, mailer is always using sync functionality. +And async when `$bus` is configured for EnvelopedMessage. + +.. code-block:: terminal + + $ composer require symfony/messenger + +.. include:: /components/require_autoload.rst.inc + + use Symfony\Component\Mailer\Mailer; + use Symfony\Component\Mailer\Messenger\MessageHandler; + use Symfony\Component\Mailer\Messenger\SendEmailMessage; + use Symfony\Component\Mailer\SmtpEnvelope; + use Symfony\Component\Mailer\Transport; + use Symfony\Component\Messenger\Handler\HandlersLocator; + use Symfony\Component\Messenger\MessageBus; + use Symfony\Component\Messenger\Middleware\HandleMessageMiddleware; + use Symfony\Component\Mime\Address; + + // .. $dsn = 'smtp://null'; + $transport = Transport::fromDsn($dsn); + $handler = new MessageHandler($transport); + + $bus = new MessageBus([ + new HandleMessageMiddleware(new HandlersLocator([ + SendEmailMessage::class => ['message_hander' => $handler], + ])), + ]); + + $mailer = new Mailer($transport, $bus); + + $mailer->send($email, new SmtpEnvelope( + new Address('sender@example.com'), + [ + new Address('recepient@example.com'), + ] + )); \ No newline at end of file From bb4c06450fccb677c90ab4e50ec484b0f6ddc3d3 Mon Sep 17 00:00:00 2001 From: Hari KT Date: Thu, 30 May 2019 23:14:16 +0530 Subject: [PATCH 2/8] Incorporate changes requested by @weaverryan --- components/mailer.rst | 42 ++++++++++++++++++++---------------------- 1 file changed, 20 insertions(+), 22 deletions(-) diff --git a/components/mailer.rst b/components/mailer.rst index 054deeb01f3..a6efcd12472 100644 --- a/components/mailer.rst +++ b/components/mailer.rst @@ -24,6 +24,8 @@ Introduction Usage ----- +The Mailer component has two main classes: a ``Transport`` and the ``Mailer`` itself:: + use Symfony\Component\Mailer\Mailer; use Symfony\Component\Mailer\Transport\Smtp\SmtpTransport; @@ -33,12 +35,13 @@ Usage Refer :doc:`Mime component ` how to create `$email` object. - Transport --------- By default, the only transport available in the mailer component is Smtp. + Below is the list of other popular providers with built in support. + - Amazon SES : symfony/amazon-mailer - Google Gmail : symfony/google-mailer - Mandrill : symfony/mailchimp-mailer @@ -52,24 +55,24 @@ For example to use google's gmail as a transport you need to install symfony/goo $ composer require symfony/google-mailer -.. include:: /components/require_autoload.rst.inc - - +.. code-block:: php use Symfony\Component\Mailer\Bridge\Google\Smtp\GmailTransport; $transport = new GmailTransport('user', 'pass'); - $transport->send($email); + $mailer = new Mailer($transport); + $mailer->send($email); Use a Dsn --------- -The mailer component provides a convenient way to create transport object from dsn string. +The mailer component provides a convenient way to create transport object from dsn string:: use Symfony\Component\Mailer\Transport; $transport = Transport::fromDsn($dsn); -Where `$dns` as one of the form below. +Where ``$dns`` as one of the form below. + - smtp://user:pass@gmail - smtp://key@sendgrid - smtp://null @@ -83,37 +86,32 @@ Easily switch from SMTP in dev to a "real" provider in production with same API. Failover transport ------------------ -You can create failover transport with the help of `||` operator. - -Eg : +You can create failover transport with the help of `||` operator:: $dsn = 'api://id@postmark || smtp://key@sendgrid'; -So if it fails at one transport, the mailer will attempt to send through the other transport. +So if the first transport fails, the mailer will attempt to send through the second transport. -RoundRobin ----------- +Round Robin +----------- -If you want to send mails via multiple transports, you can use the `&&` operator between the transports. +If you want to send emails by using multiple transports in a round-robin fashion, you can use the +``&&`` operator between the transports:: -Eg : - $dsn = 'api://id@postmark && smtp://key@sendgrid' - Async ----- -If you want to use the async functionality you need to install `messenger` component. -By default, `$bus` is null and if it is not configured, mailer is always using sync functionality. -And async when `$bus` is configured for EnvelopedMessage. +If you want to use the async functionality you need to install the ``messenger`` component. .. code-block:: terminal $ composer require symfony/messenger -.. include:: /components/require_autoload.rst.inc +Then, instantiate and pass a ``MessageBus`` as a second argument to ``Mailer``:: +.. code-block:: php use Symfony\Component\Mailer\Mailer; use Symfony\Component\Mailer\Messenger\MessageHandler; use Symfony\Component\Mailer\Messenger\SendEmailMessage; @@ -130,7 +128,7 @@ And async when `$bus` is configured for EnvelopedMessage. $bus = new MessageBus([ new HandleMessageMiddleware(new HandlersLocator([ - SendEmailMessage::class => ['message_hander' => $handler], + SendEmailMessage::class => [$handler], ])), ]); From 6e59aa67bb61dab045684835ae44b7b613d9ab11 Mon Sep 17 00:00:00 2001 From: Hari KT Date: Fri, 31 May 2019 10:50:01 +0530 Subject: [PATCH 3/8] Code level changes, as suggested by @wouterj --- components/mailer.rst | 33 +++++++++++++++++---------------- 1 file changed, 17 insertions(+), 16 deletions(-) diff --git a/components/mailer.rst b/components/mailer.rst index a6efcd12472..905a1ce779f 100644 --- a/components/mailer.rst +++ b/components/mailer.rst @@ -42,12 +42,12 @@ By default, the only transport available in the mailer component is Smtp. Below is the list of other popular providers with built in support. -- Amazon SES : symfony/amazon-mailer -- Google Gmail : symfony/google-mailer -- Mandrill : symfony/mailchimp-mailer -- Mailgun : symfony/mailgun-mailer -- Postmark : symfony/postmark-mailer -- Sendgrid : symfony/sendgrid-mailer +- Amazon SES: ``symfony/amazon-mailer`` +- Google Gmail: ``symfony/google-mailer`` +- Mandrill: ``symfony/mailchimp-mailer`` +- Mailgun: ``symfony/mailgun-mailer`` +- Postmark: ``symfony/postmark-mailer`` +- Sendgrid: ``symfony/sendgrid-mailer`` For example to use google's gmail as a transport you need to install symfony/google-mailer. @@ -56,6 +56,7 @@ For example to use google's gmail as a transport you need to install symfony/goo $ composer require symfony/google-mailer .. code-block:: php + use Symfony\Component\Mailer\Bridge\Google\Smtp\GmailTransport; $transport = new GmailTransport('user', 'pass'); @@ -73,12 +74,12 @@ The mailer component provides a convenient way to create transport object from d Where ``$dns`` as one of the form below. -- smtp://user:pass@gmail -- smtp://key@sendgrid -- smtp://null -- smtp://user:pass@mailgun -- http://key:domain@mailgun -- api://id@postmark +- ``smtp://user:pass@gmail`` +- ``smtp://key@sendgrid`` +- ``smtp://null`` +- ``smtp://user:pass@mailgun`` +- ``http://key:domain@mailgun`` +- ``api://id@postmark`` This provides a unified behaviour across all providers. Easily switch from SMTP in dev to a "real" provider in production with same API. @@ -103,7 +104,7 @@ If you want to send emails by using multiple transports in a round-robin fashion Async ----- -If you want to use the async functionality you need to install the ``messenger`` component. +If you want to use the async functionality you need to install the :doc:`Messenger component `. .. code-block:: terminal @@ -111,7 +112,6 @@ If you want to use the async functionality you need to install the ``messenger`` Then, instantiate and pass a ``MessageBus`` as a second argument to ``Mailer``:: -.. code-block:: php use Symfony\Component\Mailer\Mailer; use Symfony\Component\Mailer\Messenger\MessageHandler; use Symfony\Component\Mailer\Messenger\SendEmailMessage; @@ -121,8 +121,9 @@ Then, instantiate and pass a ``MessageBus`` as a second argument to ``Mailer``:: use Symfony\Component\Messenger\MessageBus; use Symfony\Component\Messenger\Middleware\HandleMessageMiddleware; use Symfony\Component\Mime\Address; - - // .. $dsn = 'smtp://null'; + + $dsn = 'change-dsn-accordingly'; + $transport = Transport::fromDsn($dsn); $handler = new MessageHandler($transport); From 83477abc81419dedf5afa56ef791b2df3d82fac9 Mon Sep 17 00:00:00 2001 From: Hari KT Date: Wed, 12 Jun 2019 11:45:26 +0530 Subject: [PATCH 4/8] update with changes and same format as currently merged mailer --- components/mailer.rst | 31 +++++++++++++++++++------------ 1 file changed, 19 insertions(+), 12 deletions(-) diff --git a/components/mailer.rst b/components/mailer.rst index 905a1ce779f..f45f603478f 100644 --- a/components/mailer.rst +++ b/components/mailer.rst @@ -20,6 +20,9 @@ Installation Introduction ------------ +Symfony mailer is an experimental component introduced in 4.3 which +will eventually replace swiftmailer. + Usage ----- @@ -42,14 +45,18 @@ By default, the only transport available in the mailer component is Smtp. Below is the list of other popular providers with built in support. -- Amazon SES: ``symfony/amazon-mailer`` -- Google Gmail: ``symfony/google-mailer`` -- Mandrill: ``symfony/mailchimp-mailer`` -- Mailgun: ``symfony/mailgun-mailer`` -- Postmark: ``symfony/postmark-mailer`` -- Sendgrid: ``symfony/sendgrid-mailer`` +================== ============================================= +Service Install with +================== ============================================= +Amazon SES ``composer require symfony/amazon-mailer`` +Gmail ``composer require symfony/google-mailer`` +MailChimp ``composer require symfony/mailchimp-mailer`` +Mailgun ``composer require symfony/mailgun-mailer`` +Postmark ``composer require symfony/postmark-mailer`` +SendGrid ``composer require symfony/sendgrid-mailer`` +================== ============================================= -For example to use google's gmail as a transport you need to install symfony/google-mailer. +For example, suppose you want to use Google's Gmail. First, install it: .. code-block:: terminal @@ -63,16 +70,16 @@ For example to use google's gmail as a transport you need to install symfony/goo $mailer = new Mailer($transport); $mailer->send($email); -Use a Dsn +Use a DSN --------- -The mailer component provides a convenient way to create transport object from dsn string:: +The mailer component provides a convenient way to create transport object from DSN string:: use Symfony\Component\Mailer\Transport; $transport = Transport::fromDsn($dsn); -Where ``$dns`` as one of the form below. +Where ``$dsn`` as one of the form below. - ``smtp://user:pass@gmail`` - ``smtp://key@sendgrid`` @@ -82,7 +89,7 @@ Where ``$dns`` as one of the form below. - ``api://id@postmark`` This provides a unified behaviour across all providers. -Easily switch from SMTP in dev to a "real" provider in production with same API. +Easily switch from SMTP in development to a "real" provider in production with same API. Failover transport ------------------ @@ -140,4 +147,4 @@ Then, instantiate and pass a ``MessageBus`` as a second argument to ``Mailer``:: [ new Address('recepient@example.com'), ] - )); \ No newline at end of file + )); From 9f817838da25a50b59cf3b0acf9eb135579681d9 Mon Sep 17 00:00:00 2001 From: Hari K T Date: Thu, 1 Aug 2019 20:51:40 +0530 Subject: [PATCH 5/8] Update components/mailer.rst Co-Authored-By: Antoine Makdessi --- components/mailer.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/mailer.rst b/components/mailer.rst index f45f603478f..b6753b0f58b 100644 --- a/components/mailer.rst +++ b/components/mailer.rst @@ -36,7 +36,7 @@ The Mailer component has two main classes: a ``Transport`` and the ``Mailer`` it $mailer = new Mailer($transport); $mailer->send($email); -Refer :doc:`Mime component ` how to create `$email` object. +The `$email` object is created via the :doc:`Mime component `. Transport --------- From 1b2b4d62915d572dc67d80cbb3099828196eb15f Mon Sep 17 00:00:00 2001 From: Hari K T Date: Thu, 1 Aug 2019 20:52:57 +0530 Subject: [PATCH 6/8] Update components/mailer.rst as per suggestion. Co-Authored-By: Ryan Weaver --- components/mailer.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/mailer.rst b/components/mailer.rst index b6753b0f58b..4c5d0c6f1ac 100644 --- a/components/mailer.rst +++ b/components/mailer.rst @@ -41,7 +41,7 @@ The `$email` object is created via the :doc:`Mime component `. Transport --------- -By default, the only transport available in the mailer component is Smtp. +The only transport that comes pre-installed with mailer is Smtp. Below is the list of other popular providers with built in support. From 8a680bd0b1cf23d5906756bb5ad5dad6d9e9a071 Mon Sep 17 00:00:00 2001 From: Hari KT Date: Thu, 1 Aug 2019 20:59:52 +0530 Subject: [PATCH 7/8] Add learn more --- components/mailer.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/components/mailer.rst b/components/mailer.rst index 4c5d0c6f1ac..80fae8ce601 100644 --- a/components/mailer.rst +++ b/components/mailer.rst @@ -148,3 +148,9 @@ Then, instantiate and pass a ``MessageBus`` as a second argument to ``Mailer``:: new Address('recepient@example.com'), ] )); + + +Learn More +----------- + +To learn more about how to use the mailer component, refer to the :doc:`Symfony Framework Mailer documentation `. \ No newline at end of file From f17952cbbfa4c7d4942227dfe7c3ac8ee00f9cd6 Mon Sep 17 00:00:00 2001 From: Hari KT Date: Thu, 1 Aug 2019 21:01:07 +0530 Subject: [PATCH 8/8] Remove extra line --- components/mailer.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/components/mailer.rst b/components/mailer.rst index 80fae8ce601..ef82639e94a 100644 --- a/components/mailer.rst +++ b/components/mailer.rst @@ -149,7 +149,6 @@ Then, instantiate and pass a ``MessageBus`` as a second argument to ``Mailer``:: ] )); - Learn More -----------