...

...

@@ -6,29 +6,41 @@

6

6

<refpurpose>Format a local time/date according to locale settings</refpurpose>

7

7

</refnamediv>

8

8

9

+

<refsynopsisdiv>

10

+

&warn.deprecated.function-8-1-0.alternatives;

11

+

<simplelist role="alternatives">

12

+

<member><function>date</function></member>

13

+

<member><methodname>IntlDateFormatter::format</methodname></member>

14

+

</simplelist>

15

+

</refsynopsisdiv>

16

+

9

17

<refsect1 role="description">

10

18

&reftitle.description;

11

19

<methodsynopsis>

12

-

<type>string</type><methodname>strftime</methodname>

20

+

<type class="union"><type>string</type><type>false</type></type><methodname>strftime</methodname>

13

21

<methodparam><type>string</type><parameter>format</parameter></methodparam>

14

-

<methodparam choice="opt"><type>int</type><parameter>timestamp</parameter><initializer>time()</initializer></methodparam>

22

+

<methodparam choice="opt"><type class="union"><type>int</type><type>null</type></type><parameter>timestamp</parameter><initializer>&null;</initializer></methodparam>

15

23

</methodsynopsis>

16

24

<para>

17

25

Format the time and/or date according to locale settings. Month and weekday

18

26

names and other language-dependent strings respect the current locale set

19

27

with <function>setlocale</function>.

20

28

</para>

21

-

<para>

22

-

Not all conversion specifiers may be supported by your C library, in which

23

-

case they will not be supported by PHP's <function>strftime</function>.

24

-

Additionally, not all platforms support negative timestamps, so your

25

-

date range may be limited to no earlier than the Unix epoch. This means that

26

-

%e, %T, %R and, %D (and possibly others) - as well as dates prior to

27

-

<literal>Jan 1, 1970</literal> - will not work on Windows, some Linux

28

-

distributions, and a few other operating systems. For Windows systems, a

29

-

complete overview of supported conversion specifiers can be found at

30

-

<link xlink:href="&url.strftime.win32;"><acronym>MSDN</acronym></link>.

31

-

</para>

29

+

<warning>

30

+

<para>

31

+

Not all conversion specifiers may be supported by your C library, in which

32

+

case they will not be supported by PHP's <function>strftime</function>.

33

+

Additionally, not all platforms support negative timestamps, so your

34

+

date range may be limited to no earlier than the Unix epoch. This means that

35

+

%e, %T, %R and, %D (and possibly others) - as well as dates prior to

36

+

<literal>Jan 1, 1970</literal> - will not work on Windows, some Linux

37

+

distributions, and a few other operating systems. For Windows systems, a

38

+

complete overview of supported conversion specifiers can be found at

39

+

<link xlink:href="&url.strftime.win32;"><acronym>MSDN</acronym></link>.

40

+

Instead use the

41

+

<methodname>IntlDateFormatter::format</methodname> method.

42

+

</para>

43

+

</warning>

32

44

</refsect1>

33

45

34

46

<refsect1 role="parameters">

...

...

@@ -87,7 +99,7 @@

87

99

<row>

88

100

<entry><literal>%u</literal></entry>

89

101

<entry>ISO-8601 numeric representation of the day of the week</entry>

90

-

<entry><literal>1</literal> (for Monday) though <literal>7</literal> (for Sunday)</entry>

102

+

<entry><literal>1</literal> (for Monday) through <literal>7</literal> (for Sunday)</entry>

91

103

</row>

92

104

<row>

93

105

<entry><literal>%w</literal></entry>

...

...

@@ -186,13 +198,18 @@

186

198

<entry><literal>00</literal> through <literal>23</literal></entry>

187

199

</row>

188

200

<row>

201

+

<entry><literal>%k</literal></entry>

202

+

<entry>Hour in 24-hour format, with a space preceding single digits</entry>

203

+

<entry><literal> 0</literal> through <literal>23</literal></entry>

204

+

</row>

205

+

<row>

189

206

<entry><literal>%I</literal></entry>

190

207

<entry>Two digit representation of the hour in 12-hour format</entry>

191

208

<entry><literal>01</literal> through <literal>12</literal></entry>

192

209

</row>

193

210

<row>

194

211

<entry><literal>%l (lower-case 'L')</literal></entry>

195

-

<entry>Hour in 12-hour format, with a space preceeding single digits</entry>

212

+

<entry>Hour in 12-hour format, with a space preceding single digits</entry>

196

213

<entry><literal> 1</literal> through <literal>12</literal></entry>

197

214

</row>

198

215

<row>

...

...

@@ -203,12 +220,17 @@

203

220

<row>

204

221

<entry><literal>%p</literal></entry>

205

222

<entry>UPPER-CASE 'AM' or 'PM' based on the given time</entry>

206

-

<entry>Example: <literal>AM</literal> for 00:31, <literal>PM</literal> for 22:23</entry>

223

+

<entry>Example: <literal>AM</literal> for 00:31,

224

+

<literal>PM</literal> for 22:23. The exact result depends on the

225

+

Operating System, and they can also return lower-case variants, or

226

+

variants with dots (such as <literal>a.m.</literal>).</entry>

207

227

</row>

208

228

<row>

209

229

<entry><literal>%P</literal></entry>

210

230

<entry>lower-case 'am' or 'pm' based on the given time</entry>

211

-

<entry>Example: <literal>am</literal> for 00:31, <literal>pm</literal> for 22:23</entry>

231

+

<entry>Example: <literal>am</literal> for 00:31,

232

+

<literal>pm</literal> for 22:23. Not supported by all Operating

233

+

Systems.</entry>

212

234

</row>

213

235

<row>

214

236

<entry><literal>%r</literal></entry>

...

...

@@ -237,15 +259,15 @@

237

259

</row>

238

260

<row>

239

261

<entry><literal>%z</literal></entry>

240

-

<entry>Either the time zone offset from UTC or the abbreviation (depends

241

-

on operating system)</entry>

242

-

<entry>Example: <literal>-0500</literal> or <literal>EST</literal> for Eastern Time</entry>

262

+

<entry>The time zone offset. Not implemented as described on

263

+

Windows. See below for more information.</entry>

264

+

<entry>Example: <literal>-0500</literal> for US Eastern Time</entry>

243

265

</row>

244

266

<row>

245

267

<entry><literal>%Z</literal></entry>

246

-

<entry>The time zone offset/abbreviation option NOT given by %z (depends

247

-

on operating system)</entry>

248

-

<entry>Example: <literal>-0500</literal> or <literal>EST</literal> for Eastern Time</entry>

268

+

<entry>The time zone abbreviation. Not implemented as described on

269

+

Windows. See below for more information.</entry>

270

+

<entry>Example: <literal>EST</literal> for Eastern Time</entry>

249

271

</row>

250

272

<row>

251

273

<entry align="center"><emphasis>Time and Date Stamps</emphasis></entry>

...

...

@@ -254,7 +276,7 @@

254

276

</row>

255

277

<row>

256

278

<entry><literal>%c</literal></entry>

257

-

<entry>Preferred date and time stamp based on local</entry>

279

+

<entry>Preferred date and time stamp based on locale</entry>

258

280

<entry>Example: <literal>Tue Feb 5 00:45:10 2009</literal> for

259

281

February 5, 2009 at 12:45:10 AM</entry>

260

282

</row>

...

...

@@ -303,27 +325,32 @@

303

325

</tgroup>

304

326

</table>

305

327

</para>

306

-

<para>

307

-

Maximum length of this parameter is 1023 characters.

308

-

</para>

309

328

<warning>

310

329

<simpara>

311

-

Contrary to ISO-9899:1999, Sun Solaris starts with Sunday as 1.

312

-

As a result, %u may not function as described in this manual.

330

+

Contrary to ISO-9899:1999, Sun Solaris starts with Sunday as 1. As a

331

+

result, <literal>%u</literal> may not function as described in this

332

+

manual.

313

333

</simpara>

314

334

</warning>

315

335

<warning>

316

-

<simpara>

317

-

<emphasis>Windows only:</emphasis> The <literal>%e</literal> modifier

318

-

is not supported in the Windows implementation of this function. To achieve

319

-

this value, the <literal>%#d</literal> modifier can be used instead. The

320

-

example below illustrates how to write a cross platform compatible function.

321

-

</simpara>

336

+

<para>

337

+

<emphasis>Windows only:</emphasis>

338

+

</para>

339

+

<para>

340

+

The <literal>%e</literal> modifier is not supported in the Windows

341

+

implementation of this function. To achieve this value, the

342

+

<literal>%#d</literal> modifier can be used instead. The example below

343

+

illustrates how to write a cross platform compatible function.

344

+

</para>

345

+

<para>

346

+

The <literal>%z</literal> and <literal>%Z</literal> modifiers both

347

+

return the time zone name instead of the offset or abbreviation.

348

+

</para>

322

349

</warning>

323

350

<warning>

324

351

<simpara>

325

-

<emphasis>Mac OS X only:</emphasis> The <literal>%P</literal> modifier

326

-

is not supported in the Mac OS X implementation of this function.

352

+

<emphasis>macOS and musl only:</emphasis> The <literal>%P</literal> modifier

353

+

is not supported in the macOS implementation of this function.

327

354

</simpara>

328

355

</warning>

329

356

</listitem>

...

...

@@ -343,6 +370,9 @@

343

370

local time if no timestamp is given. Month and weekday names and

344

371

other language-dependent strings respect the current locale set

345

372

with <function>setlocale</function>.

373

+

The function returns &false; if <parameter>format</parameter> is empty, contains unsupported

374

+

conversion specifiers, or if the length of the returned string would be greater than

375

+

<literal>4095</literal>.

346

376

</para>

347

377

</refsect1>

348

378

...

...

@@ -371,9 +401,12 @@

371

401

</row>

372

402

</thead>

373

403

<tbody>

374

-

375

-

&date.timezone.errors.changelog;

376

-

404

+

<row>

405

+

<entry>8.0.0</entry>

406

+

<entry>

407

+

<parameter>timestamp</parameter> is nullable now.

408

+

</entry>

409

+

</row>

377

410

</tbody>

378

411

</tgroup>

379

412

</informaltable>

...

...

@@ -524,8 +557,8 @@ $strftimeFormats = array(

524

557

'h' => 'Abbreviated month name, based on the locale (an alias of %b)',

525

558

'i' => '',

526

559

'j' => 'Day of the year, 3 digits with leading zeros',

527

-

'k' => '',

528

-

'l' => 'Hour in 12-hour format, with a space preceeding single digits',

560

+

'k' => 'Hour in 24-hour format, with a space preceding single digits',

561

+

'l' => 'Hour in 12-hour format, with a space preceding single digits',

529

562

'm' => 'Two digit representation of the month',

530

563

'n' => 'A newline character ("\n")',

531

564

'o' => '',

...

...

@@ -614,8 +647,8 @@ Unknown format : 'f'

614

647

Unknown format : 'g' ( Two digit representation of the year going by ISO-8601:1988 standards (see %V) )

615

648

Unknown format : 'h' ( Abbreviated month name, based on the locale (an alias of %b) )

616

649

Unknown format : 'i'

617

-

Unknown format : 'k'

618

-

Unknown format : 'l' ( Hour in 12-hour format, with a space preceeding single digits )

650

+

Unknown format : 'k' ( Hour in 24-hour format, with a space preceding single digits )

651

+

Unknown format : 'l' ( Hour in 12-hour format, with a space preceding single digits )

619

652

Unknown format : 'n' ( A newline character ("\n") )

620

653

Unknown format : 'o'

621

654

Unknown format : 'q'

...

...

@@ -645,6 +678,8 @@ Unknown format : 'v'

645

678

&reftitle.seealso;

646

679

<para>

647

680

<simplelist>

681

+

<member><methodname>IntlDateFormatter::format</methodname></member>

682

+

<member><methodname>DateTimeInterface::format</methodname></member>

648

683

<member><link xlink:href="&url.strftime.format.designer;">Online strftime() format design tool</link></member>

649

684

<member><function>setlocale</function></member>

650

685

<member><function>mktime</function></member>

...

...

@@ -655,7 +690,6 @@ Unknown format : 'v'

655

690

</para>

656

691

</refsect1>

657

692

</refentry>

658

-

659

693

<!-- Keep this comment at the end of the file

660

694

Local variables:

661

695

mode: sgml

662

696