Skip to content

Commit 8650a1c

Browse files
javiereguiluzjaviereguiluz
committed
Merge remote-tracking branch 'upstream/7.0' into 7.0
* upstream/7.0: remove versionadded directive for Symfony 6 remove 6.x versionnaded in webhook Remove @dev Remove @dev [Routing][Security] Document the `LogoutRouteLoader` [Notifier][Webhook] Updated Webhook-supported Notifier bridges for 6.4 [Notifier][Webhook] Added documentation for Webhook in combination with the Notifier component Fix indentation - [Webhook] Add missing webhook parsers - [Webhook] Added Sendgrid's webhook support (added in 6.4) [Mailer] Updated webhook support in Mailer bridge overview for 6.4 [Webhook] Added component documentation for use in combination with Mailer Update security.rst [Mailer] Mention webhook support in Mailer bridge overview minor
2 parents e708d72 + 6de3f76 commit 8650a1c

File tree

8 files changed

+345
-58
lines changed

8 files changed

+345
-58
lines changed

‎index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,7 @@ Topics
5858
translation
5959
validation
6060
web_link
61+
webhook
6162
workflow
6263

6364
Components

‎mailer.rst

Lines changed: 19 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -93,27 +93,29 @@ native ``native://default`` Mailer uses the sendmail
9393
It's highly recommended to NOT use ``native://default`` as you cannot control
9494
how sendmail is configured (prefer using ``sendmail://default`` if possible).
9595

96+
.. _mailer_3rd_party_transport:
97+
9698
Using a 3rd Party Transport
9799
~~~~~~~~~~~~~~~~~~~~~~~~~~~
98100

99101
Instead of using your own SMTP server or sendmail binary, you can send emails
100102
via a third-party provider:
101103

102-
===================== ===============================================
103-
Service Install with
104-
===================== ===============================================
104+
===================== =============================================== ===============
105+
Service Install with Webhook support
106+
===================== =============================================== ===============
105107
`Amazon SES`_ ``composer require symfony/amazon-mailer``
106-
`Brevo`_ ``composer require symfony/brevo-mailer``
108+
`Brevo`_ ``composer require symfony/brevo-mailer`` yes
107109
`Infobip`_ ``composer require symfony/infobip-mailer``
108-
`Mailgun`_ ``composer require symfony/mailgun-mailer``
109-
`Mailjet`_ ``composer require symfony/mailjet-mailer``
110+
`Mailgun`_ ``composer require symfony/mailgun-mailer`` yes
111+
`Mailjet`_ ``composer require symfony/mailjet-mailer`` yes
110112
`MailPace`_ ``composer require symfony/mail-pace-mailer``
111113
`MailerSend`_ ``composer require symfony/mailer-send-mailer``
112114
`Mandrill`_ ``composer require symfony/mailchimp-mailer``
113-
`Postmark`_ ``composer require symfony/postmark-mailer``
115+
`Postmark`_ ``composer require symfony/postmark-mailer`` yes
114116
`Scaleway`_ ``composer require symfony/scaleway-mailer``
115-
`SendGrid`_ ``composer require symfony/sendgrid-mailer``
116-
===================== ==============================================
117+
`SendGrid`_ ``composer require symfony/sendgrid-mailer`` yes
118+
===================== =============================================== ===============
117119

118120
.. note::
119121

@@ -179,7 +181,7 @@ party provider:
179181
| | - HTTP n/a |
180182
| | - API infobip+api://KEY@BASE_URL |
181183
+------------------------+-----------------------------------------------------+
182-
| `Mailchimp Mandrill`_ | - SMTP mandrill+smtp://USERNAME:PASSWORD@default |
184+
| `Mandrill`_ | - SMTP mandrill+smtp://USERNAME:PASSWORD@default |
183185
| | - HTTP mandrill+https://KEY@default |
184186
| | - API mandrill+api://KEY@default |
185187
+------------------------+-----------------------------------------------------+
@@ -268,6 +270,12 @@ party provider:
268270
# .env
269271
MAILER_DSN=smtp://KEY:DOMAIN@smtp.eu.mailgun.org.com:25
270272
273+
.. tip::
274+
275+
Some third party mailers, when using the API, support status callback
276+
via webhooks. See the :doc:`Webhook documentation </webhook>` for more
277+
details.
278+
271279
High Availability
272280
~~~~~~~~~~~~~~~~~
273281

@@ -1484,8 +1492,8 @@ If your transport does not support tags and metadata, they will be added as cust
14841492
The following transports currently support tags and metadata:
14851493

14861494
* Brevo
1487-
* Mailchimp
14881495
* Mailgun
1496+
* Mandrill
14891497
* Postmark
14901498
* Sendgrid
14911499

‎notifier.rst

Lines changed: 12 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -55,9 +55,9 @@ to send SMS messages to mobile phones. This feature requires subscribing to
5555
a third-party service that sends SMS messages. Symfony provides integration
5656
with a couple popular SMS services:
5757

58-
================== ===================================== ===========================================================================
59-
Service Package DSN
60-
================== ===================================== ===========================================================================
58+
================== ===================================== ========================================================================================================================= ===============
59+
Service Package DSN Webhook support
60+
================== ===================================== ========================================================================================================================= ===============
6161
`46elks`_ ``symfony/forty-six-elks-notifier`` ``forty-six-elks://API_USERNAME:API_PASSWORD@default?from=FROM``
6262
`AllMySms`_ ``symfony/all-my-sms-notifier`` ``allmysms://LOGIN:APIKEY@default?from=FROM``
6363
`AmazonSns`_ ``symfony/amazon-sns-notifier`` ``sns://ACCESS_KEY:SECRET_KEY@default?region=REGION``
@@ -97,10 +97,16 @@ Service Package DSN
9797
`SpotHit`_ ``symfony/spot-hit-notifier`` ``spothit://TOKEN@default?from=FROM``
9898
`Telnyx`_ ``symfony/telnyx-notifier`` ``telnyx://API_KEY@default?from=FROM&messaging_profile_id=MESSAGING_PROFILE_ID``
9999
`TurboSms`_ ``symfony/turbo-sms-notifier`` ``turbosms://AUTH_TOKEN@default?from=FROM``
100-
`Twilio`_ ``symfony/twilio-notifier`` ``twilio://SID:TOKEN@default?from=FROM``
101-
`Vonage`_ ``symfony/vonage-notifier`` ``vonage://KEY:SECRET@default?from=FROM``
100+
`Twilio`_ ``symfony/twilio-notifier`` ``twilio://SID:TOKEN@default?from=FROM`` yes
101+
`Vonage`_ ``symfony/vonage-notifier`` ``vonage://KEY:SECRET@default?from=FROM`` yes
102102
`Yunpian`_ ``symfony/yunpian-notifier`` ``yunpian://APIKEY@default``
103-
================== ===================================== ===========================================================================
103+
================== ===================================== ========================================================================================================================= ===============
104+
105+
.. tip::
106+
107+
Some third party transports, when using the API, support status callback
108+
via webhooks. See the :doc:`Webhook documentation </webhook>` for more
109+
details.
104110

105111
To enable a texter, add the correct DSN in your ``.env`` file and
106112
configure the ``texter_transports``:

‎reference/attributes.rst

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,11 @@ Messenger
7171

7272
* :ref:`AsMessageHandler <messenger-handler>`
7373

74+
RemoteEvent
75+
~~~~~~~~~~~
76+
77+
* :ref:`AsRemoteEventConsumer <webhook>`
78+
7479
Routing
7580
~~~~~~~
7681

‎reference/configuration/framework.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3547,6 +3547,12 @@ enabled
35473547

35483548
Adds a `Link HTTP header`_ to the response.
35493549

3550+
webhook
3551+
~~~~~~~
3552+
3553+
The ``webhook`` option (and its children) are used to configure the webhooks
3554+
defined in your application. Read more about the options in the :ref:`Webhook documentation <webhook>`.
3555+
35503556
workflows
35513557
~~~~~~~~~
35523558

‎security.rst

Lines changed: 125 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -1587,6 +1587,7 @@ and set the ``limiter`` option to its service ID:
15871587
$globalFactory: '@limiter.ip_login'
15881588
# localFactory is the limiter for username+IP
15891589
$localFactory: '@limiter.username_ip_login'
1590+
$secret: '%kernel.secret%'
15901591
15911592
security:
15921593
firewalls:
@@ -1637,6 +1638,8 @@ and set the ``limiter`` option to its service ID:
16371638
<srv:argument type="service" id="limiter.ip_login"/>
16381639
<!-- 2nd argument is the limiter for username+IP -->
16391640
<srv:argument type="service" id="limiter.username_ip_login"/>
1641+
<!-- 3rd argument is the app secret -->
1642+
<srv:argument type="service" id="%kernel.secret%"/>
16401643
</srv:service>
16411644
</srv:services>
16421645
@@ -1679,6 +1682,8 @@ and set the ``limiter`` option to its service ID:
16791682
new Reference('limiter.ip_login'),
16801683
// 2nd argument is the limiter for username+IP
16811684
new Reference('limiter.username_ip_login'),
1685+
// 3rd argument is the app secret
1686+
new Reference('kernel.secret'),
16821687
]);
16831688
16841689
$security->firewall('main')
@@ -1763,7 +1768,7 @@ To enable logging out, activate the ``logout`` config parameter under your fire
17631768
main:
17641769
# ...
17651770
logout:
1766-
path: app_logout
1771+
path: /logout
17671772
17681773
# where to redirect after logout
17691774
# target: app_any_route
@@ -1784,11 +1789,10 @@ To enable logging out, activate the ``logout`` config parameter under your fire
17841789
<!-- ... -->
17851790
17861791
<firewall name="main">
1787-
<!-- ... -->
1788-
<logout path="app_logout"/>
1792+
<logout path="/logout"/>
17891793
17901794
<!-- use "target" to configure where to redirect after logout
1791-
<logout path="app_logout" target="app_any_route"/>
1795+
<logout path="/logout" target="app_any_route"/>
17921796
-->
17931797
</firewall>
17941798
</config>
@@ -1805,69 +1809,54 @@ To enable logging out, activate the ``logout`` config parameter under your fire
18051809
$mainFirewall = $security->firewall('main');
18061810
// ...
18071811
$mainFirewall->logout()
1808-
// the argument can be either a route name or a path
1809-
->path('app_logout')
1812+
->path('/logout')
18101813
18111814
// where to redirect after logout
18121815
// ->target('app_any_route')
18131816
;
18141817
};
18151818
1816-
Next, you need to create a route for this URL (but not a controller):
1819+
Symfony will then un-authenticate users navigating to the configured ``path``,
1820+
and redirect them to the configured ``target``.
18171821

1818-
.. configuration-block::
1819-
1820-
.. code-block:: php-attributes
1822+
.. tip::
18211823

1822-
// src/Controller/SecurityController.php
1823-
namespace App\Controller;
1824+
If you need to reference the logout path, you can use the ``_logout_<firewallname>``
1825+
route name (e.g. ``_logout_main``).
18241826

1825-
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
1826-
use Symfony\Component\Routing\Annotation\Route;
1827+
If your project does not use :ref:`Symfony Flex <symfony-flex>`, make sure
1828+
you have imported the logout route loader in your routes:
18271829

1828-
class SecurityController extends AbstractController
1829-
{
1830-
#[Route('/logout', name: 'app_logout', methods: ['GET'])]
1831-
public function logout(): never
1832-
{
1833-
// controller can be blank: it will never be called!
1834-
throw new \Exception('Don\'t forget to activate logout in security.yaml');
1835-
}
1836-
}
1830+
.. configuration-block::
18371831

18381832
.. code-block:: yaml
18391833
1840-
# config/routes.yaml
1841-
app_logout:
1842-
path: /logout
1843-
methods: GET
1834+
# config/routes/security.yaml
1835+
_symfony_logout:
1836+
resource: security.route_loader.logout
1837+
type: service
18441838
18451839
.. code-block:: xml
18461840
1847-
<!-- config/routes.xml -->
1841+
<!-- config/routes/security.xml -->
18481842
<?xml version="1.0" encoding="UTF-8" ?>
18491843
<routes xmlns="http://symfony.com/schema/routing"
18501844
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
18511845
xsi:schemaLocation="http://symfony.com/schema/routing
18521846
https://symfony.com/schema/routing/routing-1.0.xsd">
18531847
1854-
<route id="app_logout" path="/logout" methods="GET"/>
1848+
<import resource="security.route_loader.logout" type="service"/>
18551849
</routes>
18561850
18571851
.. code-block:: php
18581852
1859-
// config/routes.php
1853+
// config/routes/security.php
18601854
use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
18611855
1862-
return function (RoutingConfigurator $routes): void {
1863-
$routes->add('app_logout', '/logout')
1864-
->methods(['GET'])
1865-
;
1856+
return static function (RoutingConfigurator $routes): void {
1857+
$routes->import('security.route_loader.logout', 'service');
18661858
};
18671859
1868-
That's it! By sending a user to the ``app_logout`` route (i.e. to ``/logout``)
1869-
Symfony will un-authenticate the current user and redirect them.
1870-
18711860
Logout programmatically
18721861
~~~~~~~~~~~~~~~~~~~~~~~
18731862

@@ -1945,6 +1934,105 @@ to execute custom logic::
19451934
}
19461935
}
19471936

1937+
Customizing Logout Path
1938+
~~~~~~~~~~~~~~~~~~~~~~~
1939+
1940+
Another option is to configure ``path`` as a route name. This can be useful
1941+
if you want logout URIs to be dynamic (e.g. translated according to the
1942+
current locale). In that case, you have to create this route yourself:
1943+
1944+
.. configuration-block::
1945+
1946+
.. code-block:: yaml
1947+
1948+
# config/routes.yaml
1949+
app_logout:
1950+
path:
1951+
en: /logout
1952+
fr: /deconnexion
1953+
methods: GET
1954+
1955+
.. code-block:: xml
1956+
1957+
<!-- config/routes.xml -->
1958+
<?xml version="1.0" encoding="UTF-8" ?>
1959+
<routes xmlns="http://symfony.com/schema/routing"
1960+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
1961+
xsi:schemaLocation="http://symfony.com/schema/routing
1962+
https://symfony.com/schema/routing/routing-1.0.xsd">
1963+
1964+
<route id="app_logout" path="/logout" methods="GET">
1965+
<path locale="en">/logout</path>
1966+
<path locale="fr">/deconnexion</path>
1967+
</route>
1968+
</routes>
1969+
1970+
.. code-block:: php
1971+
1972+
// config/routes.php
1973+
use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
1974+
1975+
return function (RoutingConfigurator $routes): void {
1976+
$routes->add('app_logout', [
1977+
'en' => '/logout',
1978+
'fr' => '/deconnexion',
1979+
])
1980+
->methods(['GET'])
1981+
;
1982+
};
1983+
1984+
Then, pass the route name to the ``path`` option:
1985+
1986+
.. configuration-block::
1987+
1988+
.. code-block:: yaml
1989+
1990+
# config/packages/security.yaml
1991+
security:
1992+
# ...
1993+
1994+
firewalls:
1995+
main:
1996+
# ...
1997+
logout:
1998+
path: app_logout
1999+
2000+
.. code-block:: xml
2001+
2002+
<!-- config/packages/security.xml -->
2003+
<?xml version="1.0" encoding="UTF-8" ?>
2004+
<srv:container xmlns="http://symfony.com/schema/dic/security"
2005+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
2006+
xmlns:srv="http://symfony.com/schema/dic/services"
2007+
xsi:schemaLocation="http://symfony.com/schema/dic/services
2008+
https://symfony.com/schema/dic/services/services-1.0.xsd
2009+
http://symfony.com/schema/dic/security
2010+
https://symfony.com/schema/dic/security/security-1.0.xsd">
2011+
2012+
<config>
2013+
<!-- ... -->
2014+
2015+
<firewall name="main">
2016+
<logout path="app_logout"/>
2017+
</firewall>
2018+
</config>
2019+
</srv:container>
2020+
2021+
.. code-block:: php
2022+
2023+
// config/packages/security.php
2024+
use Symfony\Config\SecurityConfig;
2025+
2026+
return static function (SecurityConfig $security): void {
2027+
// ...
2028+
2029+
$mainFirewall = $security->firewall('main');
2030+
// ...
2031+
$mainFirewall->logout()
2032+
->path('app_logout')
2033+
;
2034+
};
2035+
19482036
.. _retrieving-the-user-object:
19492037

19502038
Fetching the User Object

0 commit comments

Comments
 (0)