minor #9298 [FrameworkBundle] PR #26213 Document redirections with 307/308 HTTP status codes (ZipoKing, javiereguiluz)

This PR was merged into the master branch.

Discussion
----------

[FrameworkBundle] PR #26213 Document redirections with 307/308 HTTP status codes

This documents changes introduced with pull request symfony/symfony#26213

Commits
-------

9468bf9 Reword and added an example
c8ce65d Changes after @Simperfit  review
b3984d0 [PR #26213 Document redirections with 307/308 HTTP status codes

Author: javiereguiluz

routing/redirect_in_config.rst

@@ -155,3 +155,98 @@ action:
     Because you are redirecting to a route instead of a path, the required
     option is called ``route`` in the ``redirect()`` action, instead of ``path``
     in the ``urlRedirect()`` action.
+
+Keeping the Request Method when Redirecting
+-------------------------------------------
+
+The redirections performed in the previous examples use the ``301`` and ``302``
+HTTP status codes. For legacy reasons, these HTTP redirections change the method
+of ``POST`` requests to ``GET`` (because redirecting a ``POST`` request didn't
+work well in old browsers).
+
+However, in some scenarios it's either expected or required that the redirection
+request uses the same HTTP method. That's why the HTTP standard defines two
+additional status codes (``307`` and ``308``) to perform temporary/permanent
+redirects that maintain the original request method.
+
+The :method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\RedirectController::urlRedirectAction`
+and :method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\RedirectController::redirectAction`
+methods accept an additional argument called ``keepRequestMethod``. When it's
+set to ``true``, temporary redirects use ``307`` code instead of ``302`` and
+permanent redirects use ``308`` code instead of ``301``::
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/routes.yaml
+
+        # redirects with the 308 status code
+        route_foo:
+            # ...
+            controller: Symfony\Bundle\FrameworkBundle\Controller\RedirectController::redirectAction
+            defaults:
+                # ...
+                permanent: true
+                keepRequestMethod: true
+
+        # redirects with the 307 status code
+        route_bar:
+            # ...
+            controller: Symfony\Bundle\FrameworkBundle\Controller\RedirectController::redirectAction
+            defaults:
+                # ...
+                permanent: false
+                keepRequestMethod: true
+
+    .. 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
+                http://symfony.com/schema/routing/routing-1.0.xsd">
+
+            <!-- redirects with the 308 status code -->
+            <route id="route_foo" path="...">
+                <!-- ... -->
+                <default key="_controller">Symfony\Bundle\FrameworkBundle\Controller\RedirectController::urlRedirectAction</default>
+                <default key="permanent">true</default>
+                <default key="keepRequestMethod">true</default>
+            </route>
+
+            <!-- redirects with the 307 status code -->
+            <route id="route_bar" path="...">
+                <!-- ... -->
+                <default key="_controller">Symfony\Bundle\FrameworkBundle\Controller\RedirectController::urlRedirectAction</default>
+                <default key="permanent">false</default>
+                <default key="keepRequestMethod">true</default>
+            </route>
+        </routes>
+
+    .. code-block:: php
+
+        // config/routes.php
+        use Symfony\Component\Routing\RouteCollection;
+        use Symfony\Component\Routing\Route;
+
+        $collection = new RouteCollection();
+
+        // redirects with the 308 status code
+        $collection->add('route_foo', new Route('...', array(
+            // ...
+            '_controller'       => 'Symfony\Bundle\FrameworkBundle\Controller\RedirectController::urlRedirectAction',
+            'permanent'         => true,
+            'keepRequestMethod' => true,
+        )));
+
+        // redirects with the 307 status code
+        $collection->add('route_bar', new Route('...', array(
+            // ...
+            '_controller'       => 'Symfony\Bundle\FrameworkBundle\Controller\RedirectController::urlRedirectAction',
+            'permanent'         => false,
+            'keepRequestMethod' => true,
+        )));
+
+        return $collection;