diff --git a/reference/network/functions/setcookie.xml b/reference/network/functions/setcookie.xml index d2f9a34e669b..72b1b3b814ee 100644 --- a/reference/network/functions/setcookie.xml +++ b/reference/network/functions/setcookie.xml @@ -18,27 +18,27 @@ boolsecure&false; boolhttponly&false; - Alternative signature available as of PHP 7.3.0 (not supported with named parameters): + Alternative signature available as of PHP 7.3.0 (not supported with named parameters): 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 before any output from your script (this is a protocol restriction). This requires that you place calls to this function prior to any output, including <html> and <head> tags as well as any whitespace. - - + + Once the cookies have been set, they can be accessed on the next page load with the $_COOKIE array. Cookie values may also exist in $_REQUEST. - + @@ -51,26 +51,26 @@ name - + The name of the cookie. - + value - + The value of the cookie. This value is stored on the clients computer; do not store sensitive information. Assuming the name is 'cookiename', this value is retrieved through $_COOKIE['cookiename'] - + expires_or_options - + The time the cookie expires. This is a Unix timestamp so is in number of seconds since the epoch. One way to set this is by adding the number of seconds before the cookie @@ -80,23 +80,21 @@ Another option is to use the mktime function. If set to 0, or omitted, the cookie will expire at the end of the session (when the browser closes). - - - - - You may notice the expires_or_options 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. - - - + + + + You may notice the expires_or_options 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. + + path - + The path on the server in which the cookie will be available on. If set to '/', the cookie will be available within the entire domain. If set to @@ -105,44 +103,44 @@ sub-directories such as /foo/bar/ of domain. The default value is the current directory that the cookie is being set in. - + domain - + The (sub)domain that the cookie is available to. Setting this to a subdomain (such as 'www.example.com') will make the cookie available to that subdomain and all other sub-domains of it (i.e. w2.www.example.com). To make the cookie available to the whole domain (including all subdomains of it), simply set the value to the domain name ('example.com', in this case). - - + + Older browsers still implementing the deprecated RFC 2109 may require a leading . to match all subdomains. - + secure - + Indicates that the cookie should only be transmitted over a secure HTTPS connection from the client. When set to &true;, the cookie will only be set if a secure connection exists. On the server-side, it's on the programmer to send this kind of cookie only on secure connection (e.g. with respect to $_SERVER["HTTPS"]). - + httponly - + When &true; the cookie will be made accessible only through the HTTP protocol. This means that the cookie won't be accessible by scripting languages, such as JavaScript. It has been suggested that @@ -150,13 +148,13 @@ XSS attacks (although it is not supported by all browsers), but that claim is often disputed. &true; or &false; - + options - + An associative array which may have any of the keys expires, path, domain, secure, httponly and samesite. @@ -169,15 +167,20 @@ same as the default values of the explicit parameters. If the samesite element is omitted, no SameSite cookie attribute is set. - - - - - To set a cookie that includes attributes that aren't among the keys listed, - use header. - - - + + + + To set a cookie that includes attributes that aren't among the keys listed, + use header. + + + + + If samesite is None then + secure must also be enabled or the cookie will be + blocked by the client. + + @@ -186,55 +189,54 @@ &reftitle.returnvalues; - + If output exists prior to calling this function, setcookie will fail and return &false;. If setcookie successfully runs, it will return &true;. This does not indicate whether the user accepted the cookie. - + &reftitle.changelog; - - - - - - &Version; - &Description; - - - - - 8.2.0 - - The date format of the cookie is now 'D, d M Y H:i:s \G\M\T'; - previously it was 'D, d-M-Y H:i:s T'. - - - - 7.3.0 - - An alternative signature supporting an options - array has been added. This signature supports also setting of the - SameSite cookie attribute. - - - - - - + + + + + &Version; + &Description; + + + + + 8.2.0 + + The date format of the cookie is now 'D, d M Y H:i:s \G\M\T'; + previously it was 'D, d-M-Y H:i:s T'. + + + + 7.3.0 + + An alternative signature supporting an options + array has been added. This signature supports also setting of the + SameSite cookie attribute. + + + + + &reftitle.examples; - + The following examples demonstrate some ways to send cookies. - - <function>setcookie</function> send example - - + + <function>setcookie</function> send example + + ]]> - - - - + + + Note that the value portion of the cookie will automatically be urlencoded when you send the cookie, and when it is received, it is automatically decoded and assigned to a variable by the same @@ -256,11 +257,10 @@ setcookie("TestCookie", $value, time()+3600, "/~rasmus/", "example.com", true); setrawcookie instead. To see the contents of our test cookie in a script, simply use one of the following examples: - - - - - + + + ]]> - - - - - - <function>setcookie</function> delete example - - When deleting a cookie you should assure that the expiration date - is in the past, to trigger the removal mechanism in your browser. - Examples follow how to delete cookies sent in previous example: - - - + + + <function>setcookie</function> delete example + + When deleting a cookie you should assure that the expiration date + is in the past, to trigger the removal mechanism in your browser. + Examples follow how to delete cookies sent in previous example: + + + ]]> - - - - - - <function>setcookie</function> and arrays - - You may also set array cookies by using array notation in the - cookie name. This has the effect of setting as many cookies as - you have array elements, but when the cookie is received by your - script, the values are all placed in an array with the cookie's - name: - - - + + + <function>setcookie</function> and arrays + + You may also set array cookies by using array notation in the + cookie name. This has the effect of setting as many cookies as + you have array elements, but when the cookie is received by your + script, the values are all placed in an array with the cookie's + name: + + + ]]> - - &example.outputs; - - + &example.outputs; + + - - - - - Using separator characters such as [ and ] - as part of the cookie name is not compliant to RFC 6265, section 4, but supposed - to be supported by user agents according to RFC 6265, section 5. - - - + + + + + Using separator characters such as [ and ] + as part of the cookie name is not compliant to RFC 6265, section 4, but supposed + to be supported by user agents according to RFC 6265, section 5. + + &reftitle.notes; - + You can use output buffering to send output prior to the call of this function, with the overhead of all of your output to the browser being buffered in the server until you send it. You can do this @@ -350,7 +345,7 @@ one : cookieone ob_end_flush in your script, or setting the output_buffering configuration directive on in your &php.ini; or server configuration files. - + Common Pitfalls: @@ -401,15 +396,13 @@ one : cookieone &reftitle.seealso; - - - header - setrawcookie - cookies section - RFC 6265 - RFC 2109 - - + + header + setrawcookie + cookies section + RFC 6265 + RFC 2109 +