From 97e2bb7dbe5a974932d2c8387a8a75f9486ffadc Mon Sep 17 00:00:00 2001 From: kenjis Date: Fri, 16 Sep 2022 13:23:39 +0900 Subject: [PATCH] docs: add user guide --- user_guide_src/source/changelogs/v4.2.7.rst | 1 + .../source/helpers/cookie_helper.rst | 7 +++- .../source/installation/upgrade_427.rst | 39 +++++++++++++++++++ user_guide_src/source/outgoing/response.rst | 7 +++- 4 files changed, 50 insertions(+), 4 deletions(-) diff --git a/user_guide_src/source/changelogs/v4.2.7.rst b/user_guide_src/source/changelogs/v4.2.7.rst index 6aa5fa79b3cb..317d2a455a9d 100644 --- a/user_guide_src/source/changelogs/v4.2.7.rst +++ b/user_guide_src/source/changelogs/v4.2.7.rst @@ -12,6 +12,7 @@ Release Date: Unreleased BREAKING ******** +- The default values of the parameters in :php:func:`set_cookie()` and :php:meth:`CodeIgniter\\HTTP\\Response::setCookie()` has been fixed. Now the default values of ``$secure`` and ``$httponly`` are ``null``, and these values will be replaced with the ``Config\Cookie`` values. - ``Time::__toString()`` is now locale-independent. It returns database-compatible strings like '2022-09-07 12:00:00' in any locale. Enhancements diff --git a/user_guide_src/source/helpers/cookie_helper.rst b/user_guide_src/source/helpers/cookie_helper.rst index 4d61392605cb..d19f4dbe5589 100755 --- a/user_guide_src/source/helpers/cookie_helper.rst +++ b/user_guide_src/source/helpers/cookie_helper.rst @@ -29,11 +29,14 @@ The following functions are available: :param string $domain: Cookie domain (usually: .yourdomain.com) :param string $path: Cookie path :param string $prefix: Cookie name prefix. If ``''``, the default from **app/Config/Cookie.php** is used - :param bool $secure: Whether to only send the cookie through HTTPS - :param bool $httpOnly: Whether to hide the cookie from JavaScript + :param bool $secure: Whether to only send the cookie through HTTPS. If ``null``, the default from **app/Config/Cookie.php** is used + :param bool $httpOnly: Whether to hide the cookie from JavaScript. If ``null``, the default from **app/Config/Cookie.php** is used :param string $sameSite: The value for the SameSite cookie parameter. If ``null``, the default from **app/Config/Cookie.php** is used :rtype: void + .. 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. + This helper function gives you friendlier syntax to set browser cookies. Refer to the :doc:`Response Library ` for a description of its use, as this function is an alias for diff --git a/user_guide_src/source/installation/upgrade_427.rst b/user_guide_src/source/installation/upgrade_427.rst index c22e39e035fa..436e8ea32093 100644 --- a/user_guide_src/source/installation/upgrade_427.rst +++ b/user_guide_src/source/installation/upgrade_427.rst @@ -15,6 +15,45 @@ Please refer to the upgrade instructions corresponding to your installation meth Breaking Changes **************** +set_cookie() +============ + +If you do not use Secure flag or HttpOnly flag in Cookies, you do not need to do anything. + +Due to a bug, :php:func:`set_cookie()` and :php:meth:`CodeIgniter\\HTTP\\Response::setCookie()` +in the previous versions did not use the ``$secure`` and ``$httponly`` values in ``Config\Cookie``. +The following code did not issue a cookie with the secure flag even if you set ``$secure = true`` +in ``Config\Cookie``:: + + helper('cookie'); + + $cookie = [ + 'name' => $name, + 'value' => $value, + ]; + set_cookie($cookie); + // or + $this->response->setCookie($cookie); + +But now the values in ``Config\Cookie`` are used for the options that are not specified. +The above code issues a cookie with the secure flag if you set ``$secure = true`` +in ``Config\Cookie``. + +If your code depends on this bug, please change it to explicitly specify the necessary options:: + + $cookie = [ + 'name' => $name, + 'value' => $value, + 'secure' => false, // Set explicitly + 'httponly' => false, // Set explicitly + ]; + set_cookie($cookie); + // or + $this->response->setCookie($cookie); + +Others +====== + - ``Time::__toString()`` is now locale-independent. It returns database-compatible strings like '2022-09-07 12:00:00' in any locale. Most locales are not affected by this change. But in a few locales like `ar`, `fa`, ``Time::__toString()`` (or ``(string) $time`` or implicit casting to a string) no longer returns a localized datetime string. if you want to get a localized datetime string, use :ref:`Time::toDateTimeString() ` instead. Project Files diff --git a/user_guide_src/source/outgoing/response.rst b/user_guide_src/source/outgoing/response.rst index 156d2ee8c36d..f2b7b0e524e2 100644 --- a/user_guide_src/source/outgoing/response.rst +++ b/user_guide_src/source/outgoing/response.rst @@ -370,11 +370,14 @@ The methods provided by the parent class that are available are: :param string $domain: Cookie domain :param string $path: Cookie path :param string $prefix: Cookie name prefix. If set to ``''``, the default value from **app/Config/Cookie.php** will be used - :param bool $secure: Whether to only transfer the cookie through HTTPS - :param bool $httponly: Whether to only make the cookie accessible for HTTP requests (no JavaScript) + :param bool $secure: Whether to only transfer the cookie through HTTPS. If set to ``null``, the default value from **app/Config/Cookie.php** will be used + :param bool $httponly: Whether to only make the cookie accessible for HTTP requests (no JavaScript). If set to ``null``, the default value from **app/Config/Cookie.php** will be used :param string $samesite: The value for the SameSite cookie parameter. If set to ``''``, no SameSite attribute will be set on the cookie. If set to ``null``, the default value from **app/Config/Cookie.php** will be used :rtype: void + .. 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 pass information to this method so that a cookie can be set: Array Method, and Discrete Parameters: