docs: add user guide

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

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 </outgoing/response>` for
  a description of its use, as this function is an alias for

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() <time-todatetimestring>` instead.
 
 Project Files

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: