Skip to content

Commit 0cd93b0

Browse files
l-vol-vo
committed
Complete documentation about mailer integration
1 parent 52c2ca0 commit 0cd93b0

File tree

2 files changed

+166
-4
lines changed

2 files changed

+166
-4
lines changed

‎mailer.rst‎

Lines changed: 52 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,15 +27,64 @@ over SMTP by configuring the DNS in your ``.env`` file (the ``user``,
2727
# .env
2828
MAILER_DSN=smtp://user:pass@smtp.example.com:port
2929
30+
.. configuration-block::
31+
32+
.. code-block:: yaml
33+
34+
# config/packages/mailer.yaml
35+
framework:
36+
mailer:
37+
dsn: '%env(MAILER_DSN)%'
38+
39+
.. code-block:: xml
40+
41+
<!-- config/packages/mailer.xml -->
42+
<?xml version="1.0" encoding="UTF-8" ?>
43+
<container xmlns="http://symfony.com/schema/dic/services"
44+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
45+
xmlns:framework="http://symfony.com/schema/dic/symfony"
46+
xsi:schemaLocation="http://symfony.com/schema/dic/services
47+
https://symfony.com/schema/dic/services/services-1.0.xsd
48+
http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
49+
50+
<framework:config>
51+
<framework:mailer dsn="%env(MAILER_DSN)%" />
52+
</framework:config>
53+
</container>
54+
55+
.. code-block:: php
56+
57+
// config/packages/mailer.php
58+
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
59+
60+
return static function (ContainerConfigurator $containerConfigurator): void {
61+
$containerConfigurator->extension('framework', [
62+
'mailer' => [
63+
'dsn' => '%env(MAILER_DSN)%',
64+
]
65+
]);
66+
};
67+
3068
.. caution::
3169

3270
If you are migrating from Swiftmailer (and the Swiftmailer bundle), be
3371
warned that the DSN format is different.
3472

73+
Using built-in transports
74+
~~~~~~~~~~~~~~~~~~~~~~~~~
75+
76+
============ ==================================== ===========
77+
DSN protocol Example Description
78+
============ ==================================== ===========
79+
smtp smtp://user:pass@smtp.example.com:25 Mailer use an SMTP server to send emails
80+
sendmail sendmail://default Mailer use the local sendmail binary (`/usr/sbin/sendmail` with `-bs` options) to send emails
81+
native native://default Mailer use the sendmail binary and options configured in the `sendmail_path` setting of `php.ini`. On Windows hosts, Mailer fallbacks to `smtp` and `smtp_port` `php.ini` settings when `sendmail_path` is not configured.
82+
============ ==================================== ===========
83+
3584
Using a 3rd Party Transport
3685
~~~~~~~~~~~~~~~~~~~~~~~~~~~
3786

38-
Instead of using your own SMTP server, you can send emails via a 3rd party
87+
Instead of using your own SMTP server or sendmail binary, you can send emails via a 3rd party
3988
provider. Mailer supports several - install whichever you want:
4089

4190
================== =============================================
@@ -897,6 +946,8 @@ and it will select the appropriate certificate depending on the ``To`` option::
897946
$firstEncryptedEmail = $encrypter->encrypt($firstEmail);
898947
$secondEncryptedEmail = $encrypter->encrypt($secondEmail);
899948

949+
.. _multiple-email-transports:
950+
900951
Multiple Email Transports
901952
-------------------------
902953

‎reference/configuration/framework.rst‎

Lines changed: 114 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -98,7 +98,7 @@ Configuration
9898
* `cafile`_
9999
* `capath`_
100100
* `ciphers`_
101-
* `headers`_
101+
* :ref:`headers <http-headers>`
102102
* `http_version`_
103103
* `local_cert`_
104104
* `local_pk`_
@@ -126,7 +126,7 @@ Configuration
126126
* `cafile`_
127127
* `capath`_
128128
* `ciphers`_
129-
* `headers`_
129+
* :ref:`headers <http-headers>`
130130
* `http_version`_
131131
* `local_cert`_
132132
* `local_pk`_
@@ -151,6 +151,17 @@ Configuration
151151

152152
* :ref:`name <reference-lock-resources-name>`
153153

154+
* `mailer`_
155+
156+
* :ref:`dsn <mailer-dsn>`
157+
* `transports`_
158+
* `envelope`_
159+
160+
* `sender`_
161+
* `recipients`_
162+
163+
* :ref:`headers <mailer-headers>`
164+
154165
* `php_errors`_
155166

156167
* `log`_
@@ -159,7 +170,7 @@ Configuration
159170
* `profiler`_
160171

161172
* `collect`_
162-
* `dsn`_
173+
* :ref:`dsn <profiler-dsn>`
163174
* :ref:`enabled <reference-profiler-enabled>`
164175
* `only_exceptions`_
165176
* `only_master_requests`_
@@ -835,6 +846,8 @@ ciphers
835846
A list of the names of the ciphers allowed for the SSL/TLS connections. They
836847
can be separated by colons, commas or spaces (e.g. ``'RC4-SHA:TLS13-AES-128-GCM-SHA256'``).
837848

849+
.. _http-headers:
850+
838851
headers
839852
.......
840853

@@ -1039,6 +1052,8 @@ only_master_requests
10391052
When this is set to ``true``, the profiler will only be enabled on the master
10401053
requests (and not on the subrequests).
10411054

1055+
.. _profiler-dsn:
1056+
10421057
dsn
10431058
...
10441059

@@ -2819,6 +2834,102 @@ Name of the lock you want to create.
28192834
decorates: lock.invoice.store
28202835
arguments: ['@.inner', 100, 50]
28212836
2837+
mailer
2838+
~~~~~~
2839+
2840+
.. _mailer-dsn:
2841+
2842+
dsn
2843+
...
2844+
2845+
**type**: ``string``
2846+
2847+
The DSN used by the mailer. When several DSN may be used, use `transports` (see below) instead.
2848+
2849+
transports
2850+
..........
2851+
2852+
**type**: ``array``
2853+
2854+
A :ref:`list of DSN <multiple-email-transports>` that can be used by the mailer. A transport name is the key and the dsn is the value.
2855+
2856+
envelope
2857+
........
2858+
2859+
sender
2860+
""""""
2861+
2862+
**type**: ``string``
2863+
2864+
Sender used by the `Mailer`. Keep in mind that this setting override a sender set in the code.
2865+
2866+
recipients
2867+
""""""""""
2868+
2869+
**type**: ``array``
2870+
2871+
Recipients used by the `Mailer`. Keep in mind that this setting override recipients set in the code.
2872+
2873+
.. configuration-block::
2874+
2875+
.. code-block:: yaml
2876+
2877+
# config/packages/mailer.yaml
2878+
framework:
2879+
mailer:
2880+
dsn: 'smtp://localhost:25'
2881+
envelope:
2882+
recipients: ['admin@symfony.com', 'lead@symfony.com']
2883+
2884+
.. code-block:: xml
2885+
2886+
<!-- config/packages/mailer.xml -->
2887+
<?xml version="1.0" encoding="UTF-8" ?>
2888+
<container xmlns="http://symfony.com/schema/dic/services"
2889+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
2890+
xmlns:framework="http://symfony.com/schema/dic/symfony"
2891+
xsi:schemaLocation="http://symfony.com/schema/dic/services
2892+
https://symfony.com/schema/dic/services/services-1.0.xsd
2893+
http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
2894+
2895+
<framework:config>
2896+
<framework:mailer dsn="smtp://localhost:25">
2897+
<framework:envelope>
2898+
<framework:recipient>admin@symfony.com</framework:recipient>
2899+
<framework:recipient>lead@symfony.com</framework:recipient>
2900+
</framework:envelope>
2901+
</framework:mailer>
2902+
</framework:config>
2903+
</container>
2904+
2905+
.. code-block:: php
2906+
2907+
// config/packages/mailer.php
2908+
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
2909+
2910+
return static function (ContainerConfigurator $containerConfigurator): void {
2911+
$containerConfigurator->extension('framework', [
2912+
'mailer' => [
2913+
'dsn' => 'smtp://localhost:25',
2914+
'envelope' => [
2915+
'recipients' => [
2916+
'admin@symfony.com',
2917+
'lead@symfony.com'
2918+
]
2919+
]
2920+
]
2921+
]);
2922+
};
2923+
2924+
.. _mailer-headers:
2925+
2926+
headers
2927+
.......
2928+
2929+
**type**: ``array``
2930+
2931+
Headers to add to emails. key (`name` attribute in xml format) is the header name and value the header value.
2932+
28222933
workflows
28232934
~~~~~~~~~
28242935

0 commit comments

Comments
 (0)