Merge remote-tracking branch 'upstream/7.0' into 7.0

javiereguiluz · javiereguiluz · commit 8650a1c2a3fe · 2023-12-13T15:51:27.000+01:00
* 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
diff --git a/index.rst b/index.rst
@@ -58,6 +58,7 @@ Topics
     translation
     validation
     web_link
+    webhook
     workflow
 
 Components
diff --git a/mailer.rst b/mailer.rst
@@ -93,27 +93,29 @@ native        ``native://default``                      Mailer uses the sendmail
     It's highly recommended to NOT use ``native://default`` as you cannot control
     how sendmail is configured (prefer using ``sendmail://default`` if possible).
 
+.. _mailer_3rd_party_transport:
+
 Using a 3rd Party Transport
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Instead of using your own SMTP server or sendmail binary, you can send emails
 via a third-party provider:
 
-===================== ===============================================
-Service               Install with
-===================== ===============================================
+===================== =============================================== ===============
+Service               Install with                                    Webhook support
+===================== =============================================== ===============
 `Amazon SES`_         ``composer require symfony/amazon-mailer``
-`Brevo`_              ``composer require symfony/brevo-mailer``
+`Brevo`_              ``composer require symfony/brevo-mailer``       yes
 `Infobip`_            ``composer require symfony/infobip-mailer``
-`Mailgun`_            ``composer require symfony/mailgun-mailer``
-`Mailjet`_            ``composer require symfony/mailjet-mailer``
+`Mailgun`_            ``composer require symfony/mailgun-mailer``     yes
+`Mailjet`_            ``composer require symfony/mailjet-mailer``     yes
 `MailPace`_           ``composer require symfony/mail-pace-mailer``
 `MailerSend`_         ``composer require symfony/mailer-send-mailer``
 `Mandrill`_           ``composer require symfony/mailchimp-mailer``
-`Postmark`_           ``composer require symfony/postmark-mailer``
+`Postmark`_           ``composer require symfony/postmark-mailer``    yes
 `Scaleway`_           ``composer require symfony/scaleway-mailer``
-`SendGrid`_           ``composer require symfony/sendgrid-mailer``
-===================== ==============================================
+`SendGrid`_           ``composer require symfony/sendgrid-mailer``    yes
+===================== =============================================== ===============
 
 .. note::
 
@@ -179,7 +181,7 @@ party provider:
 |                        | - HTTP n/a                                          |
 |                        | - API infobip+api://KEY@BASE_URL                    |
 +------------------------+-----------------------------------------------------+
-| `Mailchimp Mandrill`_  | - SMTP mandrill+smtp://USERNAME:PASSWORD@default    |
+| `Mandrill`_            | - SMTP mandrill+smtp://USERNAME:PASSWORD@default    |
 |                        | - HTTP mandrill+https://KEY@default                 |
 |                        | - API mandrill+api://KEY@default                    |
 +------------------------+-----------------------------------------------------+
@@ -268,6 +270,12 @@ party provider:
         # .env
         MAILER_DSN=smtp://KEY:DOMAIN@smtp.eu.mailgun.org.com:25
 
+.. tip::
+
+    Some third party mailers, when using the API, support status callback
+    via webhooks. See the :doc:`Webhook documentation </webhook>` for more
+    details.
+
 High Availability
 ~~~~~~~~~~~~~~~~~
 
@@ -1484,8 +1492,8 @@ If your transport does not support tags and metadata, they will be added as cust
 The following transports currently support tags and metadata:
 
 * Brevo
-* Mailchimp
 * Mailgun
+* Mandrill
 * Postmark
 * Sendgrid
 
diff --git a/notifier.rst b/notifier.rst
@@ -55,9 +55,9 @@ to send SMS messages to mobile phones. This feature requires subscribing to
 a third-party service that sends SMS messages. Symfony provides integration
 with a couple popular SMS services:
 
-==================  =====================================  ===========================================================================
-Service             Package                                DSN
-==================  =====================================  ===========================================================================
+==================  =====================================  ========================================================================================================================= ===============
+Service             Package                                DSN                                                                                                                       Webhook support
+==================  =====================================  ========================================================================================================================= ===============
 `46elks`_           ``symfony/forty-six-elks-notifier``    ``forty-six-elks://API_USERNAME:API_PASSWORD@default?from=FROM``
 `AllMySms`_         ``symfony/all-my-sms-notifier``        ``allmysms://LOGIN:APIKEY@default?from=FROM``
 `AmazonSns`_        ``symfony/amazon-sns-notifier``        ``sns://ACCESS_KEY:SECRET_KEY@default?region=REGION``
@@ -97,10 +97,16 @@ Service             Package                                DSN
 `SpotHit`_          ``symfony/spot-hit-notifier``          ``spothit://TOKEN@default?from=FROM``
 `Telnyx`_           ``symfony/telnyx-notifier``            ``telnyx://API_KEY@default?from=FROM&messaging_profile_id=MESSAGING_PROFILE_ID``
 `TurboSms`_         ``symfony/turbo-sms-notifier``         ``turbosms://AUTH_TOKEN@default?from=FROM``
-`Twilio`_           ``symfony/twilio-notifier``            ``twilio://SID:TOKEN@default?from=FROM``
-`Vonage`_           ``symfony/vonage-notifier``            ``vonage://KEY:SECRET@default?from=FROM``
+`Twilio`_           ``symfony/twilio-notifier``            ``twilio://SID:TOKEN@default?from=FROM``                                                                                  yes
+`Vonage`_           ``symfony/vonage-notifier``            ``vonage://KEY:SECRET@default?from=FROM``                                                                                 yes
 `Yunpian`_          ``symfony/yunpian-notifier``           ``yunpian://APIKEY@default``
-==================  =====================================  ===========================================================================
+==================  =====================================  ========================================================================================================================= ===============
+
+.. tip::
+
+    Some third party transports, when using the API, support status callback
+    via webhooks. See the :doc:`Webhook documentation </webhook>` for more
+    details.
 
 To enable a texter, add the correct DSN in your ``.env`` file and
 configure the ``texter_transports``:
diff --git a/reference/attributes.rst b/reference/attributes.rst
@@ -71,6 +71,11 @@ Messenger
 
 * :ref:`AsMessageHandler <messenger-handler>`
 
+RemoteEvent
+~~~~~~~~~~~
+
+* :ref:`AsRemoteEventConsumer <webhook>`
+
 Routing
 ~~~~~~~
 
diff --git a/reference/configuration/framework.rst b/reference/configuration/framework.rst
@@ -3547,6 +3547,12 @@ enabled
 
 Adds a `Link HTTP header`_ to the response.
 
+webhook
+~~~~~~~
+
+The ``webhook`` option (and its children) are used to configure the webhooks
+defined in your application. Read more about the options in the :ref:`Webhook documentation <webhook>`.
+
 workflows
 ~~~~~~~~~
 
diff --git a/security.rst b/security.rst
@@ -1587,6 +1587,7 @@ and set the ``limiter`` option to its service ID:
                     $globalFactory: '@limiter.ip_login'
                     # localFactory is the limiter for username+IP
                     $localFactory: '@limiter.username_ip_login'
+                    $secret: '%kernel.secret%'
 
         security:
             firewalls:
@@ -1637,6 +1638,8 @@ and set the ``limiter`` option to its service ID:
                     <srv:argument type="service" id="limiter.ip_login"/>
                     <!-- 2nd argument is the limiter for username+IP -->
                     <srv:argument type="service" id="limiter.username_ip_login"/>
+                    <!-- 3rd argument is the app secret -->
+                    <srv:argument type="service" id="%kernel.secret%"/>
                 </srv:service>
             </srv:services>
 
@@ -1679,6 +1682,8 @@ and set the ``limiter`` option to its service ID:
                     new Reference('limiter.ip_login'),
                     // 2nd argument is the limiter for username+IP
                     new Reference('limiter.username_ip_login'),
+                    // 3rd argument is the app secret
+                    new Reference('kernel.secret'),
                 ]);
 
             $security->firewall('main')
@@ -1763,7 +1768,7 @@ To enable logging out, activate the  ``logout`` config parameter under your fire
                 main:
                     # ...
                     logout:
-                        path: app_logout
+                        path: /logout
 
                         # where to redirect after logout
                         # target: app_any_route
@@ -1784,11 +1789,10 @@ To enable logging out, activate the  ``logout`` config parameter under your fire
                 <!-- ... -->
 
                 <firewall name="main">
-                    <!-- ... -->
-                    <logout path="app_logout"/>
+                    <logout path="/logout"/>
 
                     <!-- use "target" to configure where to redirect after logout
-                    <logout path="app_logout" target="app_any_route"/>
+                    <logout path="/logout" target="app_any_route"/>
                     -->
                 </firewall>
             </config>
@@ -1805,69 +1809,54 @@ To enable logging out, activate the  ``logout`` config parameter under your fire
             $mainFirewall = $security->firewall('main');
             // ...
             $mainFirewall->logout()
-                // the argument can be either a route name or a path
-                ->path('app_logout')
+                ->path('/logout')
 
                 // where to redirect after logout
                 // ->target('app_any_route')
             ;
         };
 
-Next, you need to create a route for this URL (but not a controller):
+Symfony will then un-authenticate users navigating to the configured ``path``,
+and redirect them to the configured ``target``.
 
-.. configuration-block::
-
-    .. code-block:: php-attributes
+.. tip::
 
-        // src/Controller/SecurityController.php
-        namespace App\Controller;
+    If you need to reference the logout path, you can use the ``_logout_<firewallname>``
+    route name (e.g. ``_logout_main``).
 
-        use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
-        use Symfony\Component\Routing\Annotation\Route;
+If your project does not use :ref:`Symfony Flex <symfony-flex>`, make sure
+you have imported the logout route loader in your routes:
 
-        class SecurityController extends AbstractController
-        {
-            #[Route('/logout', name: 'app_logout', methods: ['GET'])]
-            public function logout(): never
-            {
-                // controller can be blank: it will never be called!
-                throw new \Exception('Don\'t forget to activate logout in security.yaml');
-            }
-        }
+.. configuration-block::
 
     .. code-block:: yaml
 
-        # config/routes.yaml
-        app_logout:
-            path: /logout
-            methods: GET
+        # config/routes/security.yaml
+        _symfony_logout:
+            resource: security.route_loader.logout
+            type: service
 
     .. code-block:: xml
 
-        <!-- config/routes.xml -->
+        <!-- config/routes/security.xml -->
         <?xml version="1.0" encoding="UTF-8" ?>
         <routes xmlns="http://symfony.com/schema/routing"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/routing
                 https://symfony.com/schema/routing/routing-1.0.xsd">
 
-            <route id="app_logout" path="/logout" methods="GET"/>
+            <import resource="security.route_loader.logout" type="service"/>
         </routes>
 
     .. code-block:: php
 
-        // config/routes.php
+        // config/routes/security.php
         use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
 
-        return function (RoutingConfigurator $routes): void {
-            $routes->add('app_logout', '/logout')
-                ->methods(['GET'])
-            ;
+        return static function (RoutingConfigurator $routes): void {
+            $routes->import('security.route_loader.logout', 'service');
         };
 
-That's it! By sending a user to the ``app_logout`` route (i.e. to ``/logout``)
-Symfony will un-authenticate the current user and redirect them.
-
 Logout programmatically
 ~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -1945,6 +1934,105 @@ to execute custom logic::
         }
     }
 
+Customizing Logout Path
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Another option is to configure ``path`` as a route name. This can be useful
+if you want logout URIs to be dynamic (e.g. translated according to the
+current locale). In that case, you have to create this route yourself:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/routes.yaml
+        app_logout:
+            path:
+                en: /logout
+                fr: /deconnexion
+            methods: GET
+
+    .. code-block:: xml
+
+        <!-- config/routes.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <routes xmlns="http://symfony.com/schema/routing"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/routing
+                https://symfony.com/schema/routing/routing-1.0.xsd">
+
+            <route id="app_logout" path="/logout" methods="GET">
+                <path locale="en">/logout</path>
+                <path locale="fr">/deconnexion</path>
+            </route>
+        </routes>
+
+    .. code-block:: php
+
+        // config/routes.php
+        use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
+
+        return function (RoutingConfigurator $routes): void {
+            $routes->add('app_logout', [
+                'en' => '/logout',
+                'fr' => '/deconnexion',
+            ])
+                ->methods(['GET'])
+            ;
+        };
+
+Then, pass the route name to the ``path`` option:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/security.yaml
+        security:
+            # ...
+
+            firewalls:
+                main:
+                    # ...
+                    logout:
+                        path: app_logout
+
+    .. code-block:: xml
+
+        <!-- config/packages/security.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <srv:container xmlns="http://symfony.com/schema/dic/security"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:srv="http://symfony.com/schema/dic/services"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/security
+                https://symfony.com/schema/dic/security/security-1.0.xsd">
+
+            <config>
+                <!-- ... -->
+
+                <firewall name="main">
+                    <logout path="app_logout"/>
+                </firewall>
+            </config>
+        </srv:container>
+
+    .. code-block:: php
+
+        // config/packages/security.php
+        use Symfony\Config\SecurityConfig;
+
+        return static function (SecurityConfig $security): void {
+            // ...
+
+            $mainFirewall = $security->firewall('main');
+            // ...
+            $mainFirewall->logout()
+                ->path('app_logout')
+            ;
+        };
+
 .. _retrieving-the-user-object:
 
 Fetching the User Object
diff --git a/setup.rst b/setup.rst
diff --git a/webhook.rst b/webhook.rst
