docs: add user guide

Author: kenjis

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,43 @@ Please refer to the upgrade instructions corresponding to your installation meth
 Breaking Changes
 ****************
 
+set_cookie()
+============
+
+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: