...

...

@@ -6,29 +6,42 @@

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

+

<modifier role="attribute">#[\Deprecated]</modifier>

21

+

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

13

22

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

14

-

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

23

+

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

15

24

</methodsynopsis>

16

25

<para>

17

26

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

18

27

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

19

28

with <function>setlocale</function>.

20

29

</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>

30

+

<warning>

31

+

<para>

32

+

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

33

+

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

34

+

Additionally, not all platforms support negative timestamps, so your

35

+

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

36

+

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

37

+

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

38

+

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

39

+

complete overview of supported conversion specifiers can be found at

40

+

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

41

+

Instead use the

42

+

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

43

+

</para>

44

+

</warning>

32

45

</refsect1>

33

46

34

47

<refsect1 role="parameters">

...

...

@@ -187,8 +200,7 @@

187

200

</row>

188

201

<row>

189

202

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

190

-

<entry>Two digit representation of the hour in 24-hour format, with

191

-

a space preceding single digits</entry>

203

+

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

192

204

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

193

205

</row>

194

206

<row>

...

...

@@ -209,12 +221,17 @@

209

221

<row>

210

222

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

211

223

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

212

-

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

224

+

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

225

+

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

226

+

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

227

+

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

213

228

</row>

214

229

<row>

215

230

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

216

231

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

217

-

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

232

+

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

233

+

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

234

+

Systems.</entry>

218

235

</row>

219

236

<row>

220

237

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

...

...

@@ -309,9 +326,6 @@

309

326

</tgroup>

310

327

</table>

311

328

</para>

312

-

<para>

313

-

Maximum length of this parameter is 1023 characters.

314

-

</para>

315

329

<warning>

316

330

<simpara>

317

331

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

...

...

@@ -336,8 +350,8 @@

336

350

</warning>

337

351

<warning>

338

352

<simpara>

339

-

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

340

-

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

353

+

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

354

+

is not supported in the macOS implementation of this function.

341

355

</simpara>

342

356

</warning>

343

357

</listitem>

...

...

@@ -357,6 +371,9 @@

357

371

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

358

372

other language-dependent strings respect the current locale set

359

373

with <function>setlocale</function>.

374

+

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

375

+

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

376

+

<literal>4095</literal>.

360

377

</para>

361

378

</refsect1>

362

379

...

...

@@ -385,9 +402,12 @@

385

402

</row>

386

403

</thead>

387

404

<tbody>

388

-

389

-

&date.timezone.errors.changelog;

390

-

405

+

<row>

406

+

<entry>8.0.0</entry>

407

+

<entry>

408

+

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

409

+

</entry>

410

+

</row>

391

411

</tbody>

392

412

</tgroup>

393

413

</informaltable>

...

...

@@ -496,11 +516,12 @@ echo strftime($format);

496

516

</para>

497

517

<para>

498

518

<example>

499

-

<title>Display all known and unknown formats.</title>

519

+

<title>Display all known and unknown formats</title>

500

520

<programlisting role="php">

501

521

<![CDATA[

502

522

<?php

503

-

// Describe the formats.

523

+

524

+

// Describe the formats

504

525

$strftimeFormats = array(

505

526

'A' => 'A full textual representation of the day',

506

527

'B' => 'Full month name, based on the locale',

...

...

@@ -557,28 +578,29 @@ $strftimeFormats = array(

557

578

'%' => 'A literal percentage character ("%")',

558

579

);

559

580

560

-

// Results.

581

+

// Results

561

582

$strftimeValues = array();

562

583

563

-

// Evaluate the formats whilst suppressing any errors.

564

-

foreach($strftimeFormats as $format => $description){

565

-

if (False !== ($value = @strftime("%{$format}"))){

584

+

// Evaluate the formats whilst suppressing any errors

585

+

foreach ($strftimeFormats as $format => $description) {

586

+

if (false !== ($value = @strftime("%{$format}"))) {

566

587

$strftimeValues[$format] = $value;

567

588

}

568

589

}

569

590

570

-

// Find the longest value.

591

+

// Find the longest value

571

592

$maxValueLength = 2 + max(array_map('strlen', $strftimeValues));

572

593

573

-

// Report known formats.

574

-

foreach($strftimeValues as $format => $value){

594

+

// Report known formats

595

+

foreach ($strftimeValues as $format => $value) {

575

596

echo "Known format : '{$format}' = ", str_pad("'{$value}'", $maxValueLength), " ( {$strftimeFormats[$format]} )\n";

576

597

}

577

598

578

-

// Report unknown formats.

579

-

foreach(array_diff_key($strftimeFormats, $strftimeValues) as $format => $description){

599

+

// Report unknown formats

600

+

foreach (array_diff_key($strftimeFormats, $strftimeValues) as $format => $description) {

580

601

echo "Unknown format : '{$format}' ", str_pad(' ', $maxValueLength), ($description ? " ( {$description} )" : ''), "\n";

581

602

}

603

+

582

604

?>

583

605

]]>

584

606

</programlisting>

...

...

@@ -659,6 +681,8 @@ Unknown format : 'v'

659

681

&reftitle.seealso;

660

682

<para>

661

683

<simplelist>

684

+

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

685

+

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

662

686

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

663

687

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

664

688

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

...

...

@@ -669,7 +693,6 @@ Unknown format : 'v'

669

693

</para>

670

694

</refsect1>

671

695

</refentry>

672

-

673

696

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

674

697

Local variables:

675

698

mode: sgml

676

699