[DOC-CVS] [doc-en] master: setcookie: Add note regarding SameSite=None and disabled Secure behavior (#4916)
[email protected] (AllenJB via GitHub)
| Newsgroups | php.doc.cvs |
|---|---|
| Message-ID | <[email protected]> |
Author: AllenJB (AllenJB)
Committer: GitHub (web-flow)
Pusher: Girgias
Date: 2026-01-05T18:10:42Z
Commit: https://github.com/php/doc-en/commit/9434c9439bb8f86d92ba5f227151432ea0b90b8f
Raw diff: https://github.com/php/doc-en/commit/9434c9439bb8f86d92ba5f227151432ea0b90b8f.diff
setcookie: Add note regarding SameSite=None and disabled Secure behavior (#4916)
* setcookie: Add note regarding SameSite=None and disabled Secure behavior
* setcookie (review amends - reviewed markup across this page)
* setcookie (review amends - CDATA indentation; Personalization)
* setcookie (review amends - trailing whitespace)
Changed paths:
M reference/network/functions/setcookie.xml
Diff:
diff --git a/reference/network/functions/setcookie.xml b/reference/network/functions/setcookie.xml
index d2f9a34e669b..3e563e5278c3 100644
--- a/reference/network/functions/setcookie.xml
+++ b/reference/network/functions/setcookie.xml
@@ -5,7 +5,7 @@
<refname>setcookie</refname>
<refpurpose>Send a cookie</refpurpose>
</refnamediv>
-
+
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
@@ -18,27 +18,27 @@
<methodparam choice="opt"><type>bool</type><parameter>secure</parameter><initializer>&false;</initializer></methodparam>
<methodparam choice="opt"><type>bool</type><parameter>httponly</parameter><initializer>&false;</initializer></methodparam>
</methodsynopsis>
- <para>Alternative signature available as of PHP 7.3.0 (not supported with named parameters):</para>
+ <simpara>Alternative signature available as of PHP 7.3.0 (not supported with named parameters):</simpara>
<methodsynopsis>
<type>bool</type><methodname>setcookie</methodname>
<methodparam><type>string</type><parameter>name</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter>value</parameter><initializer>""</initializer></methodparam>
<methodparam choice="opt"><type>array</type><parameter>options</parameter><initializer>[]</initializer></methodparam>
</methodsynopsis>
- <para>
+ <simpara>
<function>setcookie</function> defines a cookie to be sent along with the
rest of the HTTP headers. Like other headers, cookies must be sent
- <emphasis>before</emphasis> any output from your script (this is a
- protocol restriction). This requires that you place calls to this function
+ <emphasis>before</emphasis> any output from the script (this is a
+ protocol restriction). This requires that this function is called
prior to any output, including <literal><html></literal> and
<literal><head></literal> tags as well as any whitespace.
- </para>
- <para>
+ </simpara>
+ <simpara>
Once the cookies have been set, they can be accessed on the next page load
with the <varname>$_COOKIE</varname> array.
Cookie
values may also exist in <varname>$_REQUEST</varname>.
- </para>
+ </simpara>
</refsect1>
<refsect1 role="parameters">
@@ -51,26 +51,26 @@
<varlistentry>
<term><parameter>name</parameter></term>
<listitem>
- <para>
+ <simpara>
The name of the cookie.
- </para>
+ </simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>value</parameter></term>
<listitem>
- <para>
+ <simpara>
The value of the cookie. This value is stored on the clients computer;
do not store sensitive information. Assuming the
<parameter>name</parameter> is <literal>'cookiename'</literal>, this
value is retrieved through <varname>$_COOKIE['cookiename']</varname>
- </para>
+ </simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>expires_or_options</parameter></term>
<listitem>
- <para>
+ <simpara>
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 <function>mktime</function> function.
If set to <literal>0</literal>, or omitted, the cookie will expire at
the end of the session (when the browser closes).
- </para>
- <para>
- <note>
- <para>
- You may notice the <parameter>expires_or_options</parameter> parameter takes on a
- Unix timestamp, as opposed to the date format <literal>Wdy, DD-Mon-YYYY
- HH:MM:SS GMT</literal>, this is because PHP does this conversion
- internally.
- </para>
- </note>
- </para>
+ </simpara>
+ <note>
+ <simpara>
+ The <parameter>expires_or_options</parameter> parameter takes a
+ Unix timestamp, as opposed to the date format <literal>Wdy, DD-Mon-YYYY
+ HH:MM:SS GMT</literal>, because PHP does this conversion
+ internally.
+ </simpara>
+ </note>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>path</parameter></term>
<listitem>
- <para>
+ <simpara>
The path on the server in which the cookie will be available on.
If set to <literal>'/'</literal>, the cookie will be available
within the entire <parameter>domain</parameter>. If set to
@@ -105,44 +103,44 @@
sub-directories such as <literal>/foo/bar/</literal> of
<parameter>domain</parameter>. The default value is the
current directory that the cookie is being set in.
- </para>
+ </simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>domain</parameter></term>
<listitem>
- <para>
+ <simpara>
The (sub)domain that the cookie is available to. Setting this to a
subdomain (such as <literal>'www.example.com'</literal>) 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 (<literal>'example.com'</literal>, in this case).
- </para>
- <para>
+ </simpara>
+ <simpara>
Older browsers still implementing the deprecated
<link xlink:href="&url.rfc;2109">RFC 2109</link> may require a leading
<literal>.</literal> to match all subdomains.
- </para>
+ </simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>secure</parameter></term>
<listitem>
- <para>
+ <simpara>
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
<varname>$_SERVER["HTTPS"]</varname>).
- </para>
+ </simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>httponly</parameter></term>
<listitem>
- <para>
+ <simpara>
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,18 +148,18 @@
XSS attacks (although it is not supported by all browsers), but that
claim is often disputed.
&true; or &false;
- </para>
+ </simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>options</parameter></term>
<listitem>
- <para>
+ <simpara>
An associative <type>array</type> which may have any of the keys
<literal>expires</literal>, <literal>path</literal>, <literal>domain</literal>,
<literal>secure</literal>, <literal>httponly</literal> and <literal>samesite</literal>.
If any other key is present an error of level <constant>E_WARNING</constant>
- is generated. The values have the same meaning as described for the
+ is generated. The values have the same meaning as described for the
parameters with the same name. The value of the <literal>samesite</literal>
element should be either <literal>None</literal>, <literal>Lax</literal>
or <literal>Strict</literal>.
@@ -169,15 +167,20 @@
same as the default values of the explicit parameters. If the
<literal>samesite</literal> element is omitted, no SameSite cookie
attribute is set.
- </para>
- <para>
- <note>
- <para>
- To set a cookie that includes attributes that aren't among the keys listed,
- use <function>header</function>.
- </para>
- </note>
- </para>
+ </simpara>
+ <note>
+ <simpara>
+ To set a cookie that includes attributes that aren't among the keys listed,
+ use <function>header</function>.
+ </simpara>
+ </note>
+ <note>
+ <simpara>
+ If <literal>samesite</literal> is <literal>"None"</literal> then
+ <literal>secure</literal> must also be enabled or the cookie will be
+ blocked by the client.
+ </simpara>
+ </note>
</listitem>
</varlistentry>
</variablelist>
@@ -186,81 +189,83 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
- <para>
+ <simpara>
If output exists prior to calling this function,
<function>setcookie</function> will fail and return &false;. If
<function>setcookie</function> successfully runs, it will return &true;.
This does not indicate whether the user accepted the cookie.
- </para>
+ </simpara>
</refsect1>
<refsect1 role="changelog">
&reftitle.changelog;
- <para>
- <informaltable>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>&Version;</entry>
- <entry>&Description;</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>8.2.0</entry>
- <entry>
- The date format of the cookie is now <literal>'D, d M Y H:i:s \G\M\T'</literal>;
- previously it was <literal>'D, d-M-Y H:i:s T'</literal>.
- </entry>
- </row>
- <row>
- <entry>7.3.0</entry>
- <entry>
- An alternative signature supporting an <parameter>options</parameter>
- array has been added. This signature supports also setting of the
- SameSite cookie attribute.
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>&Version;</entry>
+ <entry>&Description;</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>8.2.0</entry>
+ <entry>
+ The date format of the cookie is now <literal>'D, d M Y H:i:s \G\M\T'</literal>;
+ previously it was <literal>'D, d-M-Y H:i:s T'</literal>.
+ </entry>
+ </row>
+ <row>
+ <entry>7.3.0</entry>
+ <entry>
+ An alternative signature supporting an <parameter>options</parameter>
+ array has been added. This signature supports also setting of the
+ SameSite cookie attribute.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
- <para>
- The following examples demonstrate some ways to send cookies.
- <example>
- <title><function>setcookie</function> send example</title>
- <programlisting role="php">
- <![CDATA[
+ <simpara>
+ The effects of the following examples can be observed using the browser
+ developer tools cookie list (usually in the Storage or Application tab).
+ </simpara>
+ <example>
+ <title><function>setcookie</function> send example</title>
+ <programlisting role="php">
+<![CDATA[
<?php
$value = 'something from somewhere';
+// Set a "session cookie" that expires when the browser is closed
setcookie("TestCookie", $value);
-setcookie("TestCookie", $value, time()+3600); /* expire in 1 hour */
+// Set a cookie that expires in 1 hour
+setcookie("TestCookie", $value, time()+3600);
+// Set a cookie that applies only to a specific path on a specific domain
+// Note that the domain used should match the site domain
setcookie("TestCookie", $value, time()+3600, "/~rasmus/", "example.com", true);
?>
]]>
- </programlisting>
- </example>
- </para>
- <para>
+ </programlisting>
+ </example>
+ <simpara>
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
- name as the cookie name. If you don't want this, you can use
- <function>setrawcookie</function> instead. To see
- the contents of our test cookie in a script, simply use one of the
- following examples:
- </para>
- <para>
- <informalexample>
- <programlisting role="php">
- <![CDATA[
+ urlencoded and decoded by PHP. This can be avoided by using
+ <function>setrawcookie</function> instead.
+ </simpara>
+ <simpara>
+ To see the contents of the cookies set in the above example on a later
+ request:
+ </simpara>
+ <informalexample>
+ <programlisting role="php">
+<![CDATA[
<?php
// Print an individual cookie
echo $_COOKIE["TestCookie"];
@@ -269,40 +274,38 @@ echo $_COOKIE["TestCookie"];
print_r($_COOKIE);
?>
]]>
- </programlisting>
- </informalexample>
- </para>
- <para>
- <example>
- <title><function>setcookie</function> delete example</title>
- <para>
- 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:
- </para>
- <programlisting role="php">
- <![CDATA[
+ </programlisting>
+ </informalexample>
+ <example>
+ <title><function>setcookie</function> delete example</title>
+ <simpara>
+ To delete a cookie set the expiration date to a value in the past
+ (but not zero, which is reserved for session cookies).
+ </simpara>
+ <simpara>
+ To delete the cookies set in previous example:
+ </simpara>
+ <programlisting role="php">
+<![CDATA[
<?php
// set the expiration date to one hour ago
setcookie("TestCookie", "", time() - 3600);
setcookie("TestCookie", "", time() - 3600, "/~rasmus/", "example.com", 1);
?>
]]>
- </programlisting>
- </example>
- </para>
- <para>
- <example>
- <title><function>setcookie</function> and arrays</title>
- <para>
- 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:
- </para>
- <programlisting role="php">
- <![CDATA[
+ </programlisting>
+ </example>
+ <example>
+ <title><function>setcookie</function> and arrays</title>
+ <simpara>
+ An "array of cookies" can be set by using array notation in the
+ cookie name. This has the effect of setting as many cookies as
+ there are array elements, but when the cookie is received by the
+ script, the values are all placed in an array with the cookie's
+ name:
+ </simpara>
+ <programlisting role="php">
+<![CDATA[
<?php
// set the cookies
setcookie("cookie[three]", "cookiethree");
@@ -319,38 +322,37 @@ if (isset($_COOKIE['cookie'])) {
}
?>
]]>
- </programlisting>
- &example.outputs;
- <screen>
- <![CDATA[
+ </programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
three : cookiethree
two : cookietwo
one : cookieone
]]>
- </screen>
- </example>
- <note>
- <simpara>
- Using separator characters such as <literal>[</literal> and <literal>]</literal>
- 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.
- </simpara>
- </note>
- </para>
+ </screen>
+ </example>
+ <note>
+ <simpara>
+ Using separator characters such as <literal>[</literal> and <literal>]</literal>
+ 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.
+ </simpara>
+ </note>
</refsect1>
-
+
<refsect1 role="notes">
&reftitle.notes;
<note>
- <para>
- 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
+ <simpara>
+ Output buffering can be used to allow script output prior to the
+ call of this function. All output will be buffered until it is flushed
+ (either explicitly or at the end of the script execution). This is done
by calling <function>ob_start</function> and
- <function>ob_end_flush</function> in your script, or setting the
- <literal>output_buffering</literal> configuration directive on in your
+ <function>ob_end_flush</function> in the script, or setting the
+ <literal>output_buffering</literal> configuration directive on in the
&php.ini; or server configuration files.
- </para>
+ </simpara>
</note>
<para>
Common Pitfalls:
@@ -378,18 +380,17 @@ one : cookieone
<listitem>
<simpara>
Because setting a cookie with a value of &false; will try to delete the cookie,
- you should not use boolean values. Instead, use <emphasis>0</emphasis> for &false;
+ boolean values should not be used. Instead, use <emphasis>0</emphasis> for &false;
and <emphasis>1</emphasis> for &true;.
</simpara>
</listitem>
<listitem>
<simpara>
- Cookies names can be set as array names and will be available to your
- PHP scripts as arrays but separate cookies are stored on the user's
- system. Consider <function>explode</function> to set one cookie with
- multiple names and values. It is not recommended to use
- <function>serialize</function> for this purpose, because it can result
- in security holes.
+ Cookies names can be set as array names and will be available to the
+ PHP scripts as arrays but separate cookies are stored by the browser.
+ Consider <function>json_encode</function> to set one cookie with multiple
+ names and values. It is not recommended to use <function>serialize</function>
+ for this purpose because it can result in security holes.
</simpara>
</listitem>
</itemizedlist>
@@ -401,15 +402,13 @@ one : cookieone
<refsect1 role="seealso">
&reftitle.seealso;
- <para>
- <simplelist>
- <member><function>header</function></member>
- <member><function>setrawcookie</function></member>
- <member><link linkend="features.cookies">cookies section</link></member>
- <member><link xlink:href="&url.rfc;6265">RFC 6265</link></member>
- <member><link xlink:href="&url.rfc;2109">RFC 2109</link></member>
- </simplelist>
- </para>
+ <simplelist>
+ <member><function>header</function></member>
+ <member><function>setrawcookie</function></member>
+ <member><link linkend="features.cookies">cookies section</link></member>
+ <member><link xlink:href="&url.rfc;6265">RFC 6265</link></member>
+ <member><link xlink:href="&url.rfc;2109">RFC 2109</link></member>
+ </simplelist>
</refsect1>
</refentry>