reference/network/functions/setcookie.xml
1ad4e2d550953000e2441b663226300596962ef2
...
...
@@ -8,18 +8,18 @@
8
8
9
9
<refsect1 role="description">
10
10
&reftitle.description;
11
-
<methodsynopsis role="procedural">
11
+
<methodsynopsis>
12
12
<type>bool</type><methodname>setcookie</methodname>
13
13
<methodparam><type>string</type><parameter>name</parameter></methodparam>
14
14
<methodparam choice="opt"><type>string</type><parameter>value</parameter><initializer>""</initializer></methodparam>
15
-
<methodparam choice="opt"><type>int</type><parameter>expires</parameter><initializer>0</initializer></methodparam>
15
+
<methodparam choice="opt"><type>int</type><parameter>expires_or_options</parameter><initializer>0</initializer></methodparam>
16
16
<methodparam choice="opt"><type>string</type><parameter>path</parameter><initializer>""</initializer></methodparam>
17
17
<methodparam choice="opt"><type>string</type><parameter>domain</parameter><initializer>""</initializer></methodparam>
18
18
<methodparam choice="opt"><type>bool</type><parameter>secure</parameter><initializer>&false;</initializer></methodparam>
19
19
<methodparam choice="opt"><type>bool</type><parameter>httponly</parameter><initializer>&false;</initializer></methodparam>
20
20
</methodsynopsis>
21
-
<para>Alternative signature available as of PHP 7.3.0:</para>
22
-
<methodsynopsis role="procedural">
21
+
<para>Alternative signature available as of PHP 7.3.0 (not supported with named parameters):</para>
22
+
<methodsynopsis>
23
23
<type>bool</type><methodname>setcookie</methodname>
24
24
<methodparam><type>string</type><parameter>name</parameter></methodparam>
25
25
<methodparam choice="opt"><type>string</type><parameter>value</parameter><initializer>""</initializer></methodparam>
...
...
@@ -68,22 +68,23 @@
68
68
</listitem>
69
69
</varlistentry>
70
70
<varlistentry>
71
-
<term><parameter>expires</parameter></term>
71
+
<term><parameter>expires_or_options</parameter></term>
72
72
<listitem>
73
73
<para>
74
74
The time the cookie expires. This is a Unix timestamp so is
75
-
in number of seconds since the epoch. In other words, you'll
76
-
most likely set this with the <function>time</function> function
77
-
plus the number of seconds before you want it to expire. Or
78
-
you might use <function>mktime</function>.
79
-
<literal>time()+60*60*24*30</literal> will set the cookie to
80
-
expire in 30 days. If set to 0, or omitted, the cookie will expire at
75
+
in number of seconds since the epoch.
76
+
One way to set this is by adding the number of seconds before the cookie
77
+
should expire to the result of calling <function>time</function>.
78
+
For instance, <literal>time()+60*60*24*30</literal> will set the cookie to
79
+
expire in 30 days.
80
+
Another option is to use the <function>mktime</function> function.
81
+
If set to <literal>0</literal>, or omitted, the cookie will expire at
81
82
the end of the session (when the browser closes).
82
83
</para>
83
84
<para>
84
85
<note>
85
86
<para>
86
-
You may notice the <parameter>expires</parameter> parameter takes on a
87
+
You may notice the <parameter>expires_or_options</parameter> parameter takes on a
87
88
Unix timestamp, as opposed to the date format <literal>Wdy, DD-Mon-YYYY
88
89
HH:MM:SS GMT</literal>, this is because PHP does this conversion
89
90
internally.
...
...
@@ -169,6 +170,14 @@
169
170
<literal>samesite</literal> element is omitted, no SameSite cookie
170
171
attribute is set.
171
172
</para>
173
+
<para>
174
+
<note>
175
+
<para>
176
+
To set a cookie that includes attributes that aren't among the keys listed,
177
+
use <function>header</function>.
178
+
</para>
179
+
</note>
180
+
</para>
172
181
</listitem>
173
182
</varlistentry>
174
183
</variablelist>
...
...
@@ -185,20 +194,55 @@
185
194
</para>
186
195
</refsect1>
187
196

197
+
<refsect1 role="changelog">
198
+
&reftitle.changelog;
199
+
<para>
200
+
<informaltable>
201
+
<tgroup cols="2">
202
+
<thead>
203
+
<row>
204
+
<entry>&Version;</entry>
205
+
<entry>&Description;</entry>
206
+
</row>
207
+
</thead>
208
+
<tbody>
209
+
<row>
210
+
<entry>8.2.0</entry>
211
+
<entry>
212
+
The date format of the cookie is now <literal>'D, d M Y H:i:s \G\M\T'</literal>;
213
+
previously it was <literal>'D, d-M-Y H:i:s T'</literal>.
214
+
</entry>
215
+
</row>
216
+
<row>
217
+
<entry>7.3.0</entry>
218
+
<entry>
219
+
An alternative signature supporting an <parameter>options</parameter>
220
+
array has been added. This signature supports also setting of the
221
+
SameSite cookie attribute.
222
+
</entry>
223
+
</row>
224
+
</tbody>
225
+
</tgroup>
226
+
</informaltable>
227
+
</para>
228
+
</refsect1>
229
+

188
230
<refsect1 role="examples">
189
231
&reftitle.examples;
190
232
<para>
191
-
Some examples follow how to send cookies:
233
+
The following examples demonstrate some ways to send cookies.
192
234
<example>
193
235
<title><function>setcookie</function> send example</title>
194
236
<programlisting role="php">
195
-
<![CDATA[
237
+
<![CDATA[
196
238
<?php
239
+

197
240
$value = 'something from somewhere';
198
241

199
242
setcookie("TestCookie", $value);
200
243
setcookie("TestCookie", $value, time()+3600); /* expire in 1 hour */
201
-
setcookie("TestCookie", $value, time()+3600, "/~rasmus/", "example.com", 1);
244
+
setcookie("TestCookie", $value, time()+3600, "/~rasmus/", "example.com", true);
245
+

202
246
?>
203
247
]]>
204
248
</programlisting>
...
...
@@ -216,7 +260,7 @@ setcookie("TestCookie", $value, time()+3600, "/~rasmus/", "example.com", 1);
216
260
<para>
217
261
<informalexample>
218
262
<programlisting role="php">
219
-
<![CDATA[
263
+
<![CDATA[
220
264
<?php
221
265
// Print an individual cookie
222
266
echo $_COOKIE["TestCookie"];
...
...
@@ -237,7 +281,7 @@ print_r($_COOKIE);
237
281
Examples follow how to delete cookies sent in previous example:
238
282
</para>
239
283
<programlisting role="php">
240
-
<![CDATA[
284
+
<![CDATA[
241
285
<?php
242
286
// set the expiration date to one hour ago
243
287
setcookie("TestCookie", "", time() - 3600);
...
...
@@ -258,7 +302,7 @@ setcookie("TestCookie", "", time() - 3600, "/~rasmus/", "example.com", 1);
258
302
name:
259
303
</para>
260
304
<programlisting role="php">
261
-
<![CDATA[
305
+
<![CDATA[
262
306
<?php
263
307
// set the cookies
264
308
setcookie("cookie[three]", "cookiethree");
...
...
@@ -278,7 +322,7 @@ if (isset($_COOKIE['cookie'])) {
278
322
</programlisting>
279
323
&example.outputs;
280
324
<screen>
281
-
<![CDATA[
325
+
<![CDATA[
282
326
three : cookiethree
283
327
two : cookietwo
284
328
one : cookieone
...
...
@@ -295,32 +339,6 @@ one : cookieone
295
339
</para>
296
340
</refsect1>
297
341
298
-
<refsect1 role="changelog">
299
-
&reftitle.changelog;
300
-
<para>
301
-
<informaltable>
302
-
<tgroup cols="2">
303
-
<thead>
304
-
<row>
305
-
<entry>&Version;</entry>
306
-
<entry>&Description;</entry>
307
-
</row>
308
-
</thead>
309
-
<tbody>
310
-
<row>
311
-
<entry>7.3.0</entry>
312
-
<entry>
313
-
An alternative signature supporting an <parameter>options</parameter>
314
-
array has been added. This signature supports also setting of the
315
-
SameSite cookie attribute.
316
-
</entry>
317
-
</row>
318
-
</tbody>
319
-
</tgroup>
320
-
</informaltable>
321
-
</para>
322
-
</refsect1>
323
-

324
342
<refsect1 role="notes">
325
343
&reftitle.notes;
326
344
<note>
...
...
@@ -342,7 +360,7 @@ one : cookieone
342
360
Cookies will not become visible until the next loading of a page that
343
361
the cookie should be visible for. To test if a cookie was successfully
344
362
set, check for the cookie on a next loading page before the cookie
345
-
expires. Expire time is set via the <parameter>expires</parameter>
363
+
expires. Expire time is set via the <parameter>expires_or_options</parameter>
346
364
parameter. A nice way to debug the existence of cookies is by
347
365
simply calling <literal>print_r($_COOKIE);</literal>.
348
366
</simpara>
...
...
@@ -350,11 +368,11 @@ one : cookieone
350
368
<listitem>
351
369
<simpara>
352
370
Cookies must be deleted with the same parameters as they were set with.
353
-
If the value argument is an empty string, or &false;, and all other arguments
354
-
match a previous call to setcookie, then the cookie with the specified
371
+
If the <parameter>value</parameter> argument is an empty string, and all other arguments
372
+
match a previous call to <function>setcookie</function>, then the cookie with the specified
355
373
name will be deleted from the remote client.
356
-
This is internally achieved by setting value to 'deleted' and expiration
357
-
time to one year in past.
374
+
This is internally achieved by setting value to <literal>'deleted'</literal> and expiration
375
+
time in the past.
358
376
</simpara>
359
377
</listitem>
360
378
<listitem>
361
379