From 56962f8d84813b58c83a4bc98c4d0827f39924ae Mon Sep 17 00:00:00 2001 From: kenjis Date: Mon, 23 May 2022 09:35:14 +0900 Subject: [PATCH 1/5] docs: add link to the method :php:meth: should be used, but it does not work. --- user_guide_src/source/helpers/cookie_helper.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/user_guide_src/source/helpers/cookie_helper.rst b/user_guide_src/source/helpers/cookie_helper.rst index 9ccceb54eeda..b64950222bce 100755 --- a/user_guide_src/source/helpers/cookie_helper.rst +++ b/user_guide_src/source/helpers/cookie_helper.rst @@ -37,7 +37,7 @@ The following functions are available: 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 - ``Response::setCookie()``. + :php:func:`Response::setCookie() `. .. php:function:: get_cookie($index[, $xssClean = false]) From ee41951811ae669d4606d50b46ad947d8755d7d3 Mon Sep 17 00:00:00 2001 From: kenjis Date: Mon, 23 May 2022 09:36:52 +0900 Subject: [PATCH 2/5] docs: decorate variable names and values --- .../source/helpers/cookie_helper.rst | 4 +- user_guide_src/source/outgoing/response.rst | 40 +++++++++---------- 2 files changed, 22 insertions(+), 22 deletions(-) diff --git a/user_guide_src/source/helpers/cookie_helper.rst b/user_guide_src/source/helpers/cookie_helper.rst index b64950222bce..5e94fe24ef44 100755 --- a/user_guide_src/source/helpers/cookie_helper.rst +++ b/user_guide_src/source/helpers/cookie_helper.rst @@ -31,7 +31,7 @@ The following functions are available: :param string $prefix: Cookie name prefix :param bool $secure: Whether to only send the cookie through HTTPS :param bool $httpOnly: Whether to hide the cookie from JavaScript - :param string $sameSite: The value for the SameSite cookie parameter. If null, the default from `config/App.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 This helper function gives you friendlier syntax to set browser @@ -69,7 +69,7 @@ The following functions are available: .. literalinclude:: cookie_helper/002.php This function is otherwise identical to ``set_cookie()``, except that it - does not have the value and expiration parameters. You can submit an + does not have the ``value`` and ``expire`` parameters. You can submit an array of values in the first parameter or you can set discrete parameters. diff --git a/user_guide_src/source/outgoing/response.rst b/user_guide_src/source/outgoing/response.rst index 6edafecb2bc3..4c1382a0b971 100644 --- a/user_guide_src/source/outgoing/response.rst +++ b/user_guide_src/source/outgoing/response.rst @@ -370,7 +370,7 @@ The methods provided by the parent class that are available are: :param string $prefix: Cookie name prefix :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 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 `config/App.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 Sets a cookie containing the values you specify. There are two ways to @@ -386,28 +386,28 @@ The methods provided by the parent class that are available are: **Notes** - Only the name and value are required. To delete a cookie set it with the - expiration blank. + Only the ``name`` and ``value`` are required. To delete a cookie set it with the + ``expire`` blank. - The expiration is set in **seconds**, which will be added to the current + The ``expire`` is set in **seconds**, which will be added to the current time. Do not include the time, but rather only the number of seconds - from *now* that you wish the cookie to be valid. If the expiration is + from *now* that you wish the cookie to be valid. If the ``expire`` is set to zero the cookie will only last as long as the browser is open. For site-wide cookies regardless of how your site is requested, add your - URL to the **domain** starting with a period, like this: + URL to the ``domain`` starting with a period, like this: .your-domain.com - The path is usually not needed since the method sets a root path. + The ``path`` is usually not needed since the method sets a root path. - The prefix is only needed if you need to avoid name collisions with + The ``prefix`` is only needed if you need to avoid name collisions with other identically named cookies for your server. - The secure flag is only needed if you want to make it a secure cookie + The ``secure`` flag is only needed if you want to make it a secure cookie by setting it to ``true``. - The SameSite value controls how cookies are shared between domains and sub-domains. - Allowed values are 'None', 'Lax', 'Strict' or a blank string ``''``. + The ``samesite`` value controls how cookies are shared between domains and sub-domains. + Allowed values are ``'None'``, ``'Lax'``, ``'Strict'`` or a blank string ``''``. If set to blank string, default SameSite attribute will be set. **Discrete Parameters** @@ -429,14 +429,14 @@ The methods provided by the parent class that are available are: **Notes** - Only the name is required. + Only the ``name`` is required. - The prefix is only needed if you need to avoid name collisions with + The ``prefix`` is only needed if you need to avoid name collisions with other identically named cookies for your server. - Provide a prefix if cookies should only be deleted for that subset. - Provide a domain name if cookies should only be deleted for that domain. - Provide a path name if cookies should only be deleted for that path. + Provide a ``prefix`` if cookies should only be deleted for that subset. + Provide a ``domain`` name if cookies should only be deleted for that domain. + Provide a ``path`` name if cookies should only be deleted for that path. If any of the optional parameters are empty, then the same-named cookie will be deleted across all that apply. @@ -456,10 +456,10 @@ The methods provided by the parent class that are available are: **Notes** - Only the name is required. If a prefix is specified, it will be prepended to the cookie name. + Only the ``name`` is required. If a ``prefix`` is specified, it will be prepended to the cookie name. - If no value is given, the method just checks for the existence of the named cookie. - If a value is given, then the method checks that the cookie exists, and that it + If no ``value`` is given, the method just checks for the existence of the named cookie. + If a ``value`` is given, then the method checks that the cookie exists, and that it has the prescribed value. Example: @@ -473,7 +473,7 @@ The methods provided by the parent class that are available are: :rtype: ``Cookie|Cookie[]|null`` Returns the named cookie, if found, or ``null``. - If no name is given, returns the array of ``Cookie`` objects. + If no ``name`` is given, returns the array of ``Cookie`` objects. Example: From 16c21ccb1e9a92849adf75b5a895c0c861e60d11 Mon Sep 17 00:00:00 2001 From: kenjis Date: Mon, 23 May 2022 10:27:39 +0900 Subject: [PATCH 3/5] docs: remove extraneous explanations Setting its expiry to 0 is internal implementation, so it is not needed. --- user_guide_src/source/outgoing/response.rst | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/user_guide_src/source/outgoing/response.rst b/user_guide_src/source/outgoing/response.rst index 4c1382a0b971..3a099980e7c7 100644 --- a/user_guide_src/source/outgoing/response.rst +++ b/user_guide_src/source/outgoing/response.rst @@ -425,9 +425,7 @@ The methods provided by the parent class that are available are: :param string $prefix: Cookie name prefix :rtype: void - Delete an existing cookie by setting its expiry to ``0``. - - **Notes** + Delete an existing cookie. Only the ``name`` is required. From 9defe6dc09b8376a2c64fcd8af07aa35ba8c67ba Mon Sep 17 00:00:00 2001 From: kenjis Date: Mon, 23 May 2022 10:31:47 +0900 Subject: [PATCH 4/5] docs: add a note for confusing behavior --- user_guide_src/source/helpers/cookie_helper.rst | 8 +++++++- user_guide_src/source/outgoing/response.rst | 3 +++ 2 files changed, 10 insertions(+), 1 deletion(-) diff --git a/user_guide_src/source/helpers/cookie_helper.rst b/user_guide_src/source/helpers/cookie_helper.rst index 5e94fe24ef44..683564ad652a 100755 --- a/user_guide_src/source/helpers/cookie_helper.rst +++ b/user_guide_src/source/helpers/cookie_helper.rst @@ -69,7 +69,13 @@ The following functions are available: .. literalinclude:: cookie_helper/002.php This function is otherwise identical to ``set_cookie()``, except that it - does not have the ``value`` and ``expire`` parameters. You can submit an + does not have the ``value`` and ``expire`` parameters. + + .. note:: When you use ``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. + + You can submit an array of values in the first parameter or you can set discrete parameters. diff --git a/user_guide_src/source/outgoing/response.rst b/user_guide_src/source/outgoing/response.rst index 3a099980e7c7..0e479829a2fe 100644 --- a/user_guide_src/source/outgoing/response.rst +++ b/user_guide_src/source/outgoing/response.rst @@ -394,6 +394,9 @@ The methods provided by the parent class that are available are: from *now* that you wish the cookie to be valid. If the ``expire`` is set to zero the cookie will only last as long as the browser is open. + .. note:: But if the ``value`` is set to empty string and the ``expire`` is set to ``0``, + the cookie will be deleted. + For site-wide cookies regardless of how your site is requested, add your URL to the ``domain`` starting with a period, like this: .your-domain.com From 298643d8361939d21b7ee4fe1d5c60115494d105 Mon Sep 17 00:00:00 2001 From: kenjis Date: Mon, 23 May 2022 10:35:17 +0900 Subject: [PATCH 5/5] docs: remove **Notes** --- user_guide_src/source/outgoing/response.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/user_guide_src/source/outgoing/response.rst b/user_guide_src/source/outgoing/response.rst index 0e479829a2fe..2227a166e096 100644 --- a/user_guide_src/source/outgoing/response.rst +++ b/user_guide_src/source/outgoing/response.rst @@ -384,8 +384,6 @@ The methods provided by the parent class that are available are: .. literalinclude:: response/023.php - **Notes** - Only the ``name`` and ``value`` are required. To delete a cookie set it with the ``expire`` blank.