From e063cbe1be98f6a1830a2a4b889d55e8a3b1d575 Mon Sep 17 00:00:00 2001 From: kenjis Date: Thu, 9 Nov 2023 10:55:32 +0900 Subject: [PATCH 1/6] docs: add about difference in redirec() --- user_guide_src/source/installation/upgrade_4xx.rst | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/user_guide_src/source/installation/upgrade_4xx.rst b/user_guide_src/source/installation/upgrade_4xx.rst index bf7ba85fece6..9e8ac1dbe7aa 100644 --- a/user_guide_src/source/installation/upgrade_4xx.rst +++ b/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 `_ - `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 From 6ead627af963c0c5e076d515e6f00d8d5332c44d Mon Sep 17 00:00:00 2001 From: kenjis Date: Thu, 9 Nov 2023 10:56:30 +0900 Subject: [PATCH 2/6] docs: add notes and descriptions for setting cookies --- user_guide_src/source/helpers/cookie_helper.rst | 12 +++++++++++- user_guide_src/source/outgoing/response.rst | 6 +++++- 2 files changed, 16 insertions(+), 2 deletions(-) diff --git a/user_guide_src/source/helpers/cookie_helper.rst b/user_guide_src/source/helpers/cookie_helper.rst index 10002e2a9eb5..813025adb185 100755 --- a/user_guide_src/source/helpers/cookie_helper.rst +++ b/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()`. diff --git a/user_guide_src/source/outgoing/response.rst b/user_guide_src/source/outgoing/response.rst index 539c99180eaa..7dca22dda53a 100644 --- a/user_guide_src/source/outgoing/response.rst +++ b/user_guide_src/source/outgoing/response.rst @@ -384,7 +384,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 +441,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 From cc15903bc2a80ca128e93a8578c3e84097189f31 Mon Sep 17 00:00:00 2001 From: kenjis Date: Thu, 9 Nov 2023 10:58:22 +0900 Subject: [PATCH 3/6] docs: add explanation for "global response instance" --- user_guide_src/source/outgoing/response.rst | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/user_guide_src/source/outgoing/response.rst b/user_guide_src/source/outgoing/response.rst index 7dca22dda53a..ad37311fb6e8 100644 --- a/user_guide_src/source/outgoing/response.rst +++ b/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. From d7cbe6f04b05ba48e300bb2bd12abe4ca25e1913 Mon Sep 17 00:00:00 2001 From: kenjis Date: Thu, 9 Nov 2023 10:58:54 +0900 Subject: [PATCH 4/6] docs: make it more readable --- user_guide_src/source/outgoing/response.rst | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/user_guide_src/source/outgoing/response.rst b/user_guide_src/source/outgoing/response.rst index ad37311fb6e8..4cf1c196edbb 100644 --- a/user_guide_src/source/outgoing/response.rst +++ b/user_guide_src/source/outgoing/response.rst @@ -44,13 +44,16 @@ Setting Headers --------------- 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. -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 +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. + 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. From 8778a7c2fcae7a3f17ed089df84e92023d51e051 Mon Sep 17 00:00:00 2001 From: kenjis Date: Thu, 9 Nov 2023 11:01:09 +0900 Subject: [PATCH 5/6] docs: add sub section titles --- user_guide_src/source/outgoing/response.rst | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/user_guide_src/source/outgoing/response.rst b/user_guide_src/source/outgoing/response.rst index 4cf1c196edbb..3d7b81c6970d 100644 --- a/user_guide_src/source/outgoing/response.rst +++ b/user_guide_src/source/outgoing/response.rst @@ -43,6 +43,9 @@ 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. @@ -54,12 +57,18 @@ which can be either a string or an array of values that will be combined correct 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. +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. From b0ac56d2baf4c5fb60b2d612b6ea7c954375096b Mon Sep 17 00:00:00 2001 From: kenjis Date: Thu, 9 Nov 2023 11:03:42 +0900 Subject: [PATCH 6/6] docs: add note to setting headers --- user_guide_src/source/outgoing/response.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/user_guide_src/source/outgoing/response.rst b/user_guide_src/source/outgoing/response.rst index 3d7b81c6970d..ee115350763f 100644 --- a/user_guide_src/source/outgoing/response.rst +++ b/user_guide_src/source/outgoing/response.rst @@ -57,6 +57,10 @@ which can be either a string or an array of values that will be combined correct 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. +.. 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() ^^^^^^^^^^^^^^