sigmasternchen/php-doc-en
1
0
Fork 0
mirror of https://github.com/sigmasternchen/php-doc-en synced 2025-03-16 00:48:54 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Document SameSite cookie attribute support (PHP 7.3.0)

Browse source 
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@345661 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Christoph Michael Becker 2018-09-20 10:50:01 +00:00
parent 2615e4d64d
commit ffe8f84ec5
5 changed files with 124 additions and 8 deletions

41
reference/network/functions/setcookie.xml
View file

@ -8,16 +8,22 @@
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<methodsynopsis role="procedural">
<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>int</type><parameter>expire</parameter><initializer>0</initializer></methodparam>
<methodparam choice="opt"><type>int</type><parameter>expires</parameter><initializer>0</initializer></methodparam>
<methodparam choice="opt"><type>string</type><parameter>path</parameter><initializer>""</initializer></methodparam>
<methodparam choice="opt"><type>string</type><parameter>domain</parameter><initializer>""</initializer></methodparam>
<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>
<methodsynopsis role="procedural">
<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>
<function>setcookie</function> 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 @@
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>expire</parameter></term>
<term><parameter>expires</parameter></term>
<listitem>
<para>
The time the cookie expires. This is a Unix timestamp so is
@ -76,7 +82,7 @@
<para>
<note>
<para>
You may notice the <parameter>expire</parameter> parameter takes on a
You may notice the <parameter>expires</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.
@ -145,6 +151,23 @@
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>options</parameter></term>
<listitem>
<para>
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>.
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>Lax</literal> or <literal>Strict</literal>.
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
<literal>samesite</literal> element is omitted, no SameSite cookie
attribute is set.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
@ -274,6 +297,14 @@ one : cookieone
</row>
</thead>
<tbody>
<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>
<row>
<entry>5.5.0</entry>
<entry>
@ -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 <parameter>expire</parameter>
expires. Expire time is set via the <parameter>expires</parameter>
parameter. A nice way to debug the existence of cookies is by
simply calling <literal>print_r($_COOKIE);</literal>.
</simpara>

18
reference/network/functions/setrawcookie.xml
View file

@ -8,16 +8,22 @@
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<methodsynopsis role="procedural">
<type>bool</type><methodname>setrawcookie</methodname>
<methodparam><type>string</type><parameter>name</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter>value</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>expire</parameter><initializer>0</initializer></methodparam>
<methodparam choice="opt"><type>int</type><parameter>expires</parameter><initializer>0</initializer></methodparam>
<methodparam choice="opt"><type>string</type><parameter>path</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter>domain</parameter></methodparam>
<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>
<methodsynopsis role="procedural">
<type>bool</type><methodname>setrawcookie</methodname>
<methodparam><type>string</type><parameter>name</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter>value</parameter></methodparam>
<methodparam choice="opt"><type>array</type><parameter>options</parameter><initializer>[]</initializer></methodparam>
</methodsynopsis>
<para>
<function>setrawcookie</function> is exactly the same as
<function>setcookie</function> except that the cookie value will not be
@ -52,6 +58,14 @@
</row>
</thead>
<tbody>
<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>
<row>
<entry>5.5.0</entry>
<entry>

12
reference/session/functions/session-get-cookie-params.xml
View file

@ -53,6 +53,12 @@
cookie can only be accessed through the HTTP protocol.
</simpara>
</listitem>
<listitem>
<simpara>
<link linkend="ini.session.cookie-httponly">"samesite"</link> - Controls
the cross-domain sending of the cookie.
</simpara>
</listitem>
</itemizedlist>
</para>
</refsect1>
@ -69,6 +75,12 @@
</row>
</thead>
<tbody>
<row>
<entry>7.3.0</entry>
<entry>
The "samesite" entry was added in the returned array.
</entry>
</row>
<row>
<entry>5.2.0</entry>
<entry>

34
reference/session/functions/session-set-cookie-params.xml
View file

@ -8,7 +8,7 @@
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<methodsynopsis role="procedural">
<type>bool</type><methodname>session_set_cookie_params</methodname>
<methodparam><type>int</type><parameter>lifetime</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter>path</parameter></methodparam>
@ -16,6 +16,10 @@
<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>
<methodsynopsis role="procedural">
<type>bool</type><methodname>session_set_cookie_params</methodname>
<methodparam><type>array</type><parameter>options</parameter></methodparam>
</methodsynopsis>
<para>
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 @@
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>options</parameter></term>
<listitem>
<para>
An associative <type>array</type> which may have any of the keys
<literal>lifetime</literal>, <literal>path</literal>, <literal>domain</literal>,
<literal>secure</literal>, <literal>httponly</literal> and <literal>samesite</literal>.
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>Lax</literal> or <literal>Strict</literal>.
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
<literal>samesite</literal> element is omitted, no SameSite cookie
attribute is set.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
@ -103,6 +124,14 @@
</row>
</thead>
<tbody>
<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>
<row>
<entry>7.2.0</entry>
<entry>
@ -140,6 +169,9 @@
<member>
<link linkend="ini.session.cookie-httponly">session.cookie_httponly</link>
</member>
<member>
<link linkend="ini.session.cookie-samesite">session.cookie_samesite</link>
</member>
<member><function>session_get_cookie_params</function></member>
</simplelist>
</para>

27
reference/session/ini.xml
View file

@ -94,6 +94,12 @@
<entry>PHP_INI_ALL</entry>
<entry>Available since PHP 5.2.0.</entry>
</row>
<row>
<entry><link linkend="ini.session.cookie-samesite">session.cookie_samesite</link></entry>
<entry>""</entry>
<entry>PHP_INI_ALL</entry>
<entry>Available since PHP 7.3.0.</entry>
</row>
<row>
<entry><link linkend="ini.session.use-strict-mode">session.use_strict_mode</link></entry>
<entry>"0"</entry>
@ -668,6 +674,27 @@
</listitem>
</varlistentry>
<varlistentry xml:id="ini.session.cookie-samesite">
<term>
<parameter>session.cookie_samesite</parameter>
<type>string</type>
</term>
<listitem>
<simpara>
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.
<literal>Lax</literal> and <literal>Strict</literal> mean that the cookie
will not be sent cross-domain for POST requests; <literal>Lax</literal>
will sent the cookie for cross-domain GET requests, while <literal>Strict</literal>
will not.
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.session.cache-limiter">
<term>
<parameter>session.cache_limiter</parameter>