Merge pull request #8165 from kenjis/docs-redirect-with-cookie-header

docs: add explanation about redirect and Cookies/Headers

user_guide_src/source/outgoing/response.rst

@@ -64,8 +64,15 @@ parameter. This is not case-sensitive.
 Redirect
 ========
 
-If you want to create a redirect, use the :php:func:`redirect()` function. It
-returns a ``RedirectResponse`` instance.
+If you want to create a redirect, use the :php:func:`redirect()` function.
+
+It returns a ``RedirectResponse`` instance. It is a different instance from the
+global response instance that ``Services::response()`` returns.
+
+.. warning:: If you set Cookies or Response Headers before you call ``redirect()``,
+    they are set to the global response instance, and they are not automatically
+    copied to the ``RedirectResponse`` instance. To send them, you need to call
+    the ``withCookies()`` or ``withHeaders()`` method manually.
 
 .. important:: If you want to redirect, an instance of ``RedirectResponse`` must
     be returned in a method of the :doc:`Controller <../incoming/controllers>` or
@@ -113,6 +120,30 @@ When you want to redirect back, use ``redirect()->back()``:
     It takes a visitor to "the last page viewed during the Session" when the Session is available.
     If the Session hasn't been loaded, or is otherwise unavailable, then a sanitized version of HTTP_REFERER will be used.
 
+Redirect with Cookies
+---------------------
+
+If you set Cookies before you call ``redirect()``, they are set to the global
+response instance, and they are not automatically copied to the ``RedirectResponse``
+instance.
+
+To send the Cookies, you need to call the ``withCookies()`` method manually.
+
+.. literalinclude:: ./response/034.php
+    :lines: 2-
+
+Redirect with Headers
+---------------------
+
+If you set Response Headers before you call ``redirect()``, they are set to the
+global response instance, and they are not automatically copied to the
+``RedirectResponse`` instance.
+
+To send the Headers, you need to call the ``withHeaders()`` method manually.
+
+.. literalinclude:: ./response/035.php
+    :lines: 2-
+
 .. _response-redirect-status-code:
 
 Redirect Status Code

user_guide_src/source/outgoing/response/031.php

@@ -8,9 +8,3 @@
 
 // Set a flash message.
 return redirect()->back()->with('foo', 'message');
-
-// Copies all cookies from global response instance.
-return redirect()->back()->withCookies();
-
-// Copies all headers from the global response instance.
-return redirect()->back()->withHeaders();

user_guide_src/source/outgoing/response/034.php

@@ -0,0 +1,4 @@
+<?php
+
+// Copies all cookies from global response instance.
+return redirect()->back()->withCookies();

user_guide_src/source/outgoing/response/035.php

@@ -0,0 +1,4 @@
+<?php
+
+// Copies all headers from the global response instance.
+return redirect()->back()->withHeaders();