From b3984d0ed99c82243bb905a8f54cc97885a0fc22 Mon Sep 17 00:00:00 2001 From: Pawel Smolinski Date: Mon, 19 Feb 2018 19:13:45 +0000 Subject: [PATCH 1/3] [PR #26213 Document redirections with 307/308 HTTP status codes --- routing/redirect_in_config.rst | 73 ++++++++++++++++++++++++++++++++++ 1 file changed, 73 insertions(+) diff --git a/routing/redirect_in_config.rst b/routing/redirect_in_config.rst index 89864c4c06c..a913073200b 100644 --- a/routing/redirect_in_config.rst +++ b/routing/redirect_in_config.rst @@ -155,3 +155,76 @@ 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. + +Redirecting POST/PUT calls +-------------------------- + +As default behaviour of both methods mentioned above results in sending +response with ``301`` or ``302`` HTTP status codes, the following call will +be made with use of HTTP request method. But it some scenarios it is +expected or required that following call will be made with the same HTTP +method, i.e. when initial call was ``POST`` one, then following one should +be also ``POST`` not ``GET``. In order to achieve this both +:method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\RedirectController::urlRedirectAction` +and +:method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\RedirectController::redirectAction` +are accepting aditional switch called ``keepRequestMethod``: + +.. configuration-block:: + + .. code-block:: yaml + + # config/routes.yaml + + # ... + + admin: + path: /webhooks/foo + controller: Symfony\Bundle\FrameworkBundle\Controller\RedirectController::redirectAction + defaults: + route: foo_webhook_handler + permanent: true + keepRequestMethod: true + + .. code-block:: xml + + + + + + + + `` + Symfony\Bundle\FrameworkBundle\Controller\RedirectController::redirectAction + foo_webhook_handler + true + true + + + + .. code-block:: php + + // config/routes.php + use Symfony\Component\Routing\RouteCollection; + use Symfony\Component\Routing\Route; + + $collection = new RouteCollection(); + // ... + + $collection->add('admin', new Route('/webhooks/foo', array( + '_controller' => 'Symfony\Bundle\FrameworkBundle\Controller\RedirectController::redirectAction', + 'route' => 'foo_webhook_handler', + 'permanent' => true, + 'keepRequestMethod' => true + ))); + + return $collection; + +Switching ``keepRequestMethod`` switch to ``true`` will result in sending +response with either ``307`` (when ``permament`` switch is set to false) or +``308`` (with ``permament`` being true) HTTP status code which will tell that +HTTP request should be repeated with both request method and body being +unchanged. From c8ce65dc3341abca1c348a83e4d0f8e1c100a9fb Mon Sep 17 00:00:00 2001 From: Pawel Smolinski Date: Tue, 20 Feb 2018 20:00:20 +0000 Subject: [PATCH 2/3] Changes after @Simperfit review --- routing/redirect_in_config.rst | 70 ++++------------------------------ 1 file changed, 8 insertions(+), 62 deletions(-) diff --git a/routing/redirect_in_config.rst b/routing/redirect_in_config.rst index a913073200b..d648af71f39 100644 --- a/routing/redirect_in_config.rst +++ b/routing/redirect_in_config.rst @@ -159,72 +159,18 @@ action: Redirecting POST/PUT calls -------------------------- -As default behaviour of both methods mentioned above results in sending +As a default behaviour of both methods mentioned above results in sending response with ``301`` or ``302`` HTTP status codes, the following call will -be made with use of HTTP request method. But it some scenarios it is -expected or required that following call will be made with the same HTTP +be made with use of HTTP request method. But in some scenarios it's either +expected or required that the following call will be made with the same HTTP method, i.e. when initial call was ``POST`` one, then following one should be also ``POST`` not ``GET``. In order to achieve this both :method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\RedirectController::urlRedirectAction` and :method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\RedirectController::redirectAction` -are accepting aditional switch called ``keepRequestMethod``: +are accepting aditional switch called ``keepRequestMethod``. -.. configuration-block:: - - .. code-block:: yaml - - # config/routes.yaml - - # ... - - admin: - path: /webhooks/foo - controller: Symfony\Bundle\FrameworkBundle\Controller\RedirectController::redirectAction - defaults: - route: foo_webhook_handler - permanent: true - keepRequestMethod: true - - .. code-block:: xml - - - - - - - - `` - Symfony\Bundle\FrameworkBundle\Controller\RedirectController::redirectAction - foo_webhook_handler - true - true - - - - .. code-block:: php - - // config/routes.php - use Symfony\Component\Routing\RouteCollection; - use Symfony\Component\Routing\Route; - - $collection = new RouteCollection(); - // ... - - $collection->add('admin', new Route('/webhooks/foo', array( - '_controller' => 'Symfony\Bundle\FrameworkBundle\Controller\RedirectController::redirectAction', - 'route' => 'foo_webhook_handler', - 'permanent' => true, - 'keepRequestMethod' => true - ))); - - return $collection; - -Switching ``keepRequestMethod`` switch to ``true`` will result in sending -response with either ``307`` (when ``permament`` switch is set to false) or -``308`` (with ``permament`` being true) HTTP status code which will tell that -HTTP request should be repeated with both request method and body being -unchanged. +When ``keepRequestMethod`` is set to ``true`` with either ``permanent`` set to +``false`` which will lead to a ``307`` response or ``308`` with +``permanent`` being ``true``. Theses codes will give information in the HTTP +request that the method should be repeated without altering the body. From 9468bf981005de9a7c57653449d0f766bddad645 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 26 Feb 2018 16:48:25 +0100 Subject: [PATCH 3/3] Reword and added an example I did some rewords based on https://symfony.com/blog/new-in-symfony-4-1-307-and-308-redirections and added a full config example. --- routing/redirect_in_config.rst | 110 ++++++++++++++++++++++++++++----- 1 file changed, 93 insertions(+), 17 deletions(-) diff --git a/routing/redirect_in_config.rst b/routing/redirect_in_config.rst index d648af71f39..f9babd3bb44 100644 --- a/routing/redirect_in_config.rst +++ b/routing/redirect_in_config.rst @@ -156,21 +156,97 @@ action: option is called ``route`` in the ``redirect()`` action, instead of ``path`` in the ``urlRedirect()`` action. -Redirecting POST/PUT calls --------------------------- - -As a default behaviour of both methods mentioned above results in sending -response with ``301`` or ``302`` HTTP status codes, the following call will -be made with use of HTTP request method. But in some scenarios it's either -expected or required that the following call will be made with the same HTTP -method, i.e. when initial call was ``POST`` one, then following one should -be also ``POST`` not ``GET``. In order to achieve this both -:method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\RedirectController::urlRedirectAction` -and -:method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\RedirectController::redirectAction` -are accepting aditional switch called ``keepRequestMethod``. +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 + + + + + + + + + Symfony\Bundle\FrameworkBundle\Controller\RedirectController::urlRedirectAction + true + true + + + + + + Symfony\Bundle\FrameworkBundle\Controller\RedirectController::urlRedirectAction + false + true + + + + .. 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, + ))); -When ``keepRequestMethod`` is set to ``true`` with either ``permanent`` set to -``false`` which will lead to a ``307`` response or ``308`` with -``permanent`` being ``true``. Theses codes will give information in the HTTP -request that the method should be repeated without altering the body. + // 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;