From ffe8f84ec5ec175a2b8ddf23a569d4e621866d76 Mon Sep 17 00:00:00 2001 From: Christoph Michael Becker Date: Thu, 20 Sep 2018 10:50:01 +0000 Subject: [PATCH] Document SameSite cookie attribute support (PHP 7.3.0) git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@345661 c90b9560-bf6c-de11-be94-00142212c4b1 --- reference/network/functions/setcookie.xml | 41 ++++++++++++++++--- reference/network/functions/setrawcookie.xml | 18 +++++++- .../functions/session-get-cookie-params.xml | 12 ++++++ .../functions/session-set-cookie-params.xml | 34 ++++++++++++++- reference/session/ini.xml | 27 ++++++++++++ 5 files changed, 124 insertions(+), 8 deletions(-) diff --git a/reference/network/functions/setcookie.xml b/reference/network/functions/setcookie.xml index 7a0f3d366c..e93b025653 100644 --- a/reference/network/functions/setcookie.xml +++ b/reference/network/functions/setcookie.xml @@ -8,16 +8,22 @@ &reftitle.description; - + boolsetcookie stringname stringvalue"" - intexpire0 + intexpires0 stringpath"" stringdomain"" boolsecure&false; boolhttponly&false; + + boolsetcookie + stringname + stringvalue"" + arrayoptions[] + setcookie defines a cookie to be sent along with the rest of the HTTP headers. Like other headers, cookies must be sent @@ -61,7 +67,7 @@ - expire + expires The time the cookie expires. This is a Unix timestamp so is @@ -76,7 +82,7 @@ - You may notice the expire parameter takes on a + You may notice the expires parameter takes on a Unix timestamp, as opposed to the date format Wdy, DD-Mon-YYYY HH:MM:SS GMT, this is because PHP does this conversion internally. @@ -145,6 +151,23 @@ + + options + + + An associative array which may have any of the keys + expires, path, domain, + secure, httponly and samesite. + The values have the same meaning as described for the parameters with the + same name. The value of the samesite element should be + either Lax or Strict. + If any of the allowed options are not given, their default values are the + same as the default values of the explicit parameters. If the + samesite element is omitted, no SameSite cookie + attribute is set. + + + @@ -274,6 +297,14 @@ one : cookieone + + 7.3.0 + + An alternative signature supporting an options + array has been added. This signature supports also setting of the + SameSite cookie attribute. + + 5.5.0 @@ -322,7 +353,7 @@ one : cookieone Cookies will not become visible until the next loading of a page that the cookie should be visible for. To test if a cookie was successfully set, check for the cookie on a next loading page before the cookie - expires. Expire time is set via the expire + expires. Expire time is set via the expires parameter. A nice way to debug the existence of cookies is by simply calling print_r($_COOKIE);. diff --git a/reference/network/functions/setrawcookie.xml b/reference/network/functions/setrawcookie.xml index 0e48f07ad8..b277290323 100644 --- a/reference/network/functions/setrawcookie.xml +++ b/reference/network/functions/setrawcookie.xml @@ -8,16 +8,22 @@ &reftitle.description; - + boolsetrawcookie stringname stringvalue - intexpire0 + intexpires0 stringpath stringdomain boolsecure&false; boolhttponly&false; + + boolsetrawcookie + stringname + stringvalue + arrayoptions[] + setrawcookie is exactly the same as setcookie except that the cookie value will not be @@ -52,6 +58,14 @@ + + 7.3.0 + + An alternative signature supporting an options + array has been added. This signature supports also setting of the + SameSite cookie attribute. + + 5.5.0 diff --git a/reference/session/functions/session-get-cookie-params.xml b/reference/session/functions/session-get-cookie-params.xml index 6368e2125e..917bb6584d 100644 --- a/reference/session/functions/session-get-cookie-params.xml +++ b/reference/session/functions/session-get-cookie-params.xml @@ -53,6 +53,12 @@ cookie can only be accessed through the HTTP protocol. + + + "samesite" - Controls + the cross-domain sending of the cookie. + + @@ -69,6 +75,12 @@ + + 7.3.0 + + The "samesite" entry was added in the returned array. + + 5.2.0 diff --git a/reference/session/functions/session-set-cookie-params.xml b/reference/session/functions/session-set-cookie-params.xml index aea80caa2f..2ac6c4dac7 100644 --- a/reference/session/functions/session-set-cookie-params.xml +++ b/reference/session/functions/session-set-cookie-params.xml @@ -8,7 +8,7 @@ &reftitle.description; - + boolsession_set_cookie_params intlifetime stringpath @@ -16,6 +16,10 @@ boolsecure&false; boolhttponly&false; + + boolsession_set_cookie_params + arrayoptions + Set cookie parameters defined in the &php.ini; file. The effect of this function only lasts for the duration of the script. Thus, you need to @@ -80,6 +84,23 @@ + + options + + + An associative array which may have any of the keys + lifetime, path, domain, + secure, httponly and samesite. + The values have the same meaning as described for the parameters with the + same name. The value of the samesite element should be + either Lax or Strict. + If any of the allowed options are not given, their default values are the + same as the default values of the explicit parameters. If the + samesite element is omitted, no SameSite cookie + attribute is set. + + + @@ -103,6 +124,14 @@ + + 7.3.0 + + An alternative signature supporting an options + array has been added. This signature supports also setting of the + SameSite cookie attribute. + + 7.2.0 @@ -140,6 +169,9 @@ session.cookie_httponly + + session.cookie_samesite + session_get_cookie_params diff --git a/reference/session/ini.xml b/reference/session/ini.xml index 71a3c889cd..bdf89f8cb4 100644 --- a/reference/session/ini.xml +++ b/reference/session/ini.xml @@ -94,6 +94,12 @@ PHP_INI_ALL Available since PHP 5.2.0. + + session.cookie_samesite + "" + PHP_INI_ALL + Available since PHP 7.3.0. + session.use_strict_mode "0" @@ -668,6 +674,27 @@ + + + session.cookie_samesite + string + + + + Allows servers to assert that a cookie ought not to be sent along with + cross-site requests. This assertion allows user agents to mitigate the risk + of cross-origin information leakage, and provides some protection against + cross-site request forgery attacks. Note that this is not supported by all + browsers. + An empty value means that no SameSite cookie attribute will be set. + Lax and Strict mean that the cookie + will not be sent cross-domain for POST requests; Lax + will sent the cookie for cross-domain GET requests, while Strict + will not. + + + + session.cache_limiter