...

...

@@ -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,14 +194,47 @@

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

197

239

$value = 'something from somewhere';

198

240

...

...

@@ -216,7 +258,7 @@ setcookie("TestCookie", $value, time()+3600, "/~rasmus/", "example.com", 1);

216

258

<para>

217

259

<informalexample>

218

260

<programlisting role="php">

219

-

<![CDATA[

261

+

<![CDATA[

220

262

<?php

221

263

// Print an individual cookie

222

264

echo $_COOKIE["TestCookie"];

...

...

@@ -237,7 +279,7 @@ print_r($_COOKIE);

237

279

Examples follow how to delete cookies sent in previous example:

238

280

</para>

239

281

<programlisting role="php">

240

-

<![CDATA[

282

+

<![CDATA[

241

283

<?php

242

284

// set the expiration date to one hour ago

243

285

setcookie("TestCookie", "", time() - 3600);

...

...

@@ -258,7 +300,7 @@ setcookie("TestCookie", "", time() - 3600, "/~rasmus/", "example.com", 1);

258

300

name:

259

301

</para>

260

302

<programlisting role="php">

261

-

<![CDATA[

303

+

<![CDATA[

262

304

<?php

263

305

// set the cookies

264

306

setcookie("cookie[three]", "cookiethree");

...

...

@@ -278,7 +320,7 @@ if (isset($_COOKIE['cookie'])) {

278

320

</programlisting>

279

321

&example.outputs;

280

322

<screen>

281

-

<![CDATA[

323

+

<![CDATA[

282

324

three : cookiethree

283

325

two : cookietwo

284

326

one : cookieone

...

...

@@ -295,32 +337,6 @@ one : cookieone

295

337

</para>

296

338

</refsect1>

297

339

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

340

<refsect1 role="notes">

325

341

&reftitle.notes;

326

342

<note>

...

...

@@ -342,7 +358,7 @@ one : cookieone

342

358

Cookies will not become visible until the next loading of a page that

343

359

the cookie should be visible for. To test if a cookie was successfully

344

360

set, check for the cookie on a next loading page before the cookie

345

-

expires. Expire time is set via the <parameter>expires</parameter>

361

+

expires. Expire time is set via the <parameter>expires_or_options</parameter>

346

362

parameter. A nice way to debug the existence of cookies is by

347

363

simply calling <literal>print_r($_COOKIE);</literal>.

348

364

</simpara>

...

...

@@ -350,11 +366,11 @@ one : cookieone

350

366

<listitem>

351

367

<simpara>

352

368

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

369

+

If the value argument is an empty string, and all other arguments

354

370

match a previous call to setcookie, then the cookie with the specified

355

371

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.

372

+

This is internally achieved by setting value to <literal>'deleted'</literal> and expiration

373

+

time in the past.

358

374

</simpara>

359

375

</listitem>

360

376

<listitem>

361

377