docs: add documentation

Author: kenjis

user_guide_src/source/changelogs/v4.2.1.rst

@@ -16,3 +16,4 @@ Behavior Changes
 ================
 
 - Guessing the file extension from the MIME type has been changed if the proposed extension is not valid. Previously, the guessing will early terminate and return ``null``. Now, if a proposed extension is given and is invalid, the MIME guessing will continue checking using the mapping of extension to MIME types.
+- If there is a cookie with a prefixed name and a cookie with the same name without a prefix, the previous ``get_cookie()`` had the tricky behavior of returning the cookie without the prefix. Now the behavior has been fixed as a bug, and has been changed. See :ref:`Upgrading <upgrade-421-get_cookie>` for details.

user_guide_src/source/helpers/cookie_helper.rst

@@ -39,21 +39,24 @@ The following functions are available:
     a description of its use, as this function is an alias for
     :php:func:`Response::setCookie() <setCookie>`.
 
-.. php:function:: get_cookie($index[, $xssClean = false])
+.. php:function:: get_cookie($index[, $xssClean = false[, $prefix = '']])
 
     :param    string    $index: Cookie name
     :param    bool    $xssClean: Whether to apply XSS filtering to the returned value
+    :param    string|null  $prefix: Cookie name prefix. If set to ``''``, the default value from **app/Config/Cookie.php** will be used. If set to ``null``, no prefix
     :returns:    The cookie value or null if not found
     :rtype:    mixed
 
+    .. note:: Since v4.2.1, the third parameter ``$prefix`` has been introduced and the behavior has been changed a bit due to a bug fix. See :ref:`Upgrading <upgrade-421-get_cookie>` for details.
+
     This helper function gives you friendlier syntax to get browser
     cookies. Refer to the :doc:`IncomingRequest Library </incoming/incomingrequest>` for
     detailed description of its use, as this function acts very
     similarly to ``IncomingRequest::getCookie()``, except it will also prepend
     the ``Config\Cookie::$prefix`` that you might've set in your
     **app/Config/Cookie.php** file.
 
-.. warning:: Using XSS filtering is a bad practice. It does not prevent XSS attacks perfectly. Using ``esc()`` with the correct ``$context`` in the views is recommended.
+    .. warning:: Using XSS filtering is a bad practice. It does not prevent XSS attacks perfectly. Using ``esc()`` with the correct ``$context`` in the views is recommended.
 
 .. php:function:: delete_cookie($name[, $domain = ''[, $path = '/'[, $prefix = '']]])
 

user_guide_src/source/installation/upgrade_421.rst

@@ -23,6 +23,41 @@ app/Config/Mimes.php
 Breaking Changes
 ****************
 
+.. _upgrade-421-get_cookie:
+
+get_cookie()
+============
+
+If there is a cookie with a prefixed name and a cookie with the same name without a prefix, the previous ``get_cookie()`` had the tricky behavior of returning the cookie without the prefix.
+
+For example, when ``Config\Cookie::$prefix`` is ``prefix_``, there are two cookies, ``test`` and ``prefix_test``:
+
+.. code-block:: php
+
+    $_COOKIES = [
+        'test'        => 'Non CI Cookie',
+        'prefix_test' => 'CI Cookie',
+    ];
+
+Previously, ``get_cookie()`` returns the following:
+
+.. code-block:: php
+
+    get_cookie('test');        // returns "Non CI Cookie"
+    get_cookie('prefix_test'); // returns "CI Cookie"
+
+Now the behavior has been fixed as a bug, and has been changed like the following.
+
+.. code-block:: php
+
+    get_cookie('test');              // returns "CI Cookie"
+    get_cookie('prefix_test');       // returns null
+    get_cookie('test', false, null); // returns "Non CI Cookie"
+
+If you depend on the previous behavior, you need to change your code.
+
+.. note:: In the example above, if there is only one cookie ``prefix_test``,
+    the previous ``get_cookie('test')`` also returns ``"CI Cookie"``.
 
 Breaking Enhancements
 *********************