Merge pull request #8179 from kenjis/docs-about-cookie-setting

docs: add explanation for setting cookies/headers

Author: kenjis

user_guide_src/source/helpers/cookie_helper.rst

@@ -42,6 +42,11 @@ The following functions are available:
     a description of its use, as this function is an alias for
     :php:meth:`CodeIgniter\\HTTP\\Response::setCookie()`.
 
+    .. note:: This helper function just sets browser cookies to the global response
+        instance that ``Services::response()`` returns. So, if you create and
+        return another response instance (e.g., if you call :php:func:`redirect()`),
+        the cookies set here will not be sent automatically.
+
 .. php:function:: get_cookie($index[, $xssClean = false[, $prefix = '']])
 
     :param    string    $index: Cookie name
@@ -78,6 +83,9 @@ The following functions are available:
     This function is otherwise identical to :php:func:`set_cookie()`, except that it
     does not have the ``value`` and ``expire`` parameters.
 
+    This also just sets browser cookies for deleting the cookies to the global
+    response instance that ``Services::response()`` returns.
+
     .. note:: When you use :php:func:`set_cookie()`,
         if the ``value`` is set to empty string and the ``expire`` is set to ``0``, the cookie will be deleted.
         If the ``value`` is set to non-empty string and the ``expire`` is set to ``0``, the cookie will only last as long as the browser is open.
@@ -95,4 +103,6 @@ The following functions are available:
     :param string $prefix: Cookie prefix
     :rtype: bool
 
-    Checks if a cookie exists by name. This is an alias of ``Response::hasCookie()``.
+    Checks if a cookie exists by name in the global response instance that
+    ``Services::response()`` returns. This is an alias of
+    :php:meth:`CodeIgniter\\HTTP\\Response::hasCookie()`.

user_guide_src/source/installation/upgrade_4xx.rst

@@ -142,7 +142,12 @@ Helpers
 - In CI4, ``redirect()`` is completely changed from CI3's.
     - `redirect() Documentation CodeIgniter 3.X <https://codeigniter.com/userguide3/helpers/url_helper.html#redirect>`_
     - `redirect() Documentation CodeIgniter 4.X <../general/common_functions.html#redirect>`_
-    - In CI4, ``redirect()`` returns a ``RedirectResponse`` instance instead of redirecting and terminating script execution. You must return it.
+    - In CI4, :php:func:`redirect()` returns a ``RedirectResponse`` instance instead of
+      redirecting and terminating script execution. You must return it from Controllers
+      or Controller Filters.
+    - Cookies and Headers you set before calling ``redirect()`` are not automatically
+      carried over to a ``RedirectResponse``. You need to call ``withCookies()``
+      or ``withHeaders()`` manually if you want to send them.
     - You need to change CI3's ``redirect('login/form')`` to ``return redirect()->to('login/form')``.
 
 Hooks

user_guide_src/source/outgoing/response.rst

@@ -12,8 +12,11 @@ a server responding to the client that called it.
 Working with the Response
 =========================
 
-A Response class is instantiated for you and passed into your controllers. It can be accessed through
-``$this->response``. Many times you will not need to touch the class directly, since CodeIgniter takes care of
+A Response class is instantiated for you and passed into your controllers. It can
+be accessed through ``$this->response``. It is the same instance that
+``Services::response()`` returns. We call it the global response instance.
+
+Many times you will not need to touch the class directly, since CodeIgniter takes care of
 sending the headers and the body for you. This is great if the page successfully created the content it was asked to.
 When things go wrong, or you need to send very specific status codes back, or even take advantage of the
 powerful HTTP caching, it's there for you.
@@ -40,20 +43,36 @@ You can set format an array into either JSON or XML and set the content type hea
 Setting Headers
 ---------------
 
+setHeader()
+^^^^^^^^^^^
+
 Often, you will need to set headers to be set for the response. The Response class makes this very simple to do,
-with the ``setHeader()`` method. The first parameter is the name of the header. The second parameter is the value,
+with the ``setHeader()`` method.
+
+The first parameter is the name of the header. The second parameter is the value,
 which can be either a string or an array of values that will be combined correctly when sent to the client.
+
+.. literalinclude:: response/004.php
+
 Using these functions instead of using the native PHP functions allows you to ensure that no headers are sent
 prematurely, causing errors, and makes testing possible.
 
-.. literalinclude:: response/004.php
+.. note:: This method just sets headers to the response instance. So, if you create
+    and return another response instance (e.g., if you call :php:func:`redirect()`),
+    the headers set here will not be sent automatically.
+
+appendHeader()
+^^^^^^^^^^^^^^
 
 If the header exists and can have more than one value, you may use the ``appendHeader()`` and ``prependHeader()``
 methods to add the value to the end or beginning of the values list, respectively. The first parameter is the name
 of the header, while the second is the value to append or prepend.
 
 .. literalinclude:: response/005.php
 
+removeHeader()
+^^^^^^^^^^^^^^
+
 Headers can be removed from the response with the ``removeHeader()`` method, which takes the header name as the only
 parameter. This is not case-sensitive.
 
@@ -384,7 +403,9 @@ The methods provided by the parent class that are available are:
         .. note:: Prior to v4.2.7, the default values of ``$secure`` and ``$httponly`` were ``false``
             due to a bug, and these values from **app/Config/Cookie.php** were never used.
 
-        Sets a cookie containing the values you specify. There are two ways to
+        Sets a cookie containing the values you specify to the Response instance.
+
+        There are two ways to
         pass information to this method so that a cookie can be set: Array
         Method, and Discrete Parameters:
 
@@ -439,6 +460,8 @@ The methods provided by the parent class that are available are:
 
         Delete an existing cookie.
 
+        .. note:: This also just sets browser cookie for deleting the cookie.
+
         Only the ``name`` is required.
 
         The ``prefix`` is only needed if you need to avoid name collisions with