reference/datetime/functions/strftime.xml
9b1673cf114a1e10c4563ab9223cb56aed552b89
...
...
@@ -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">
...
...
@@ -87,7 +100,7 @@
87
100
<row>
88
101
<entry><literal>%u</literal></entry>
89
102
<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>
103
+
<entry><literal>1</literal> (for Monday) through <literal>7</literal> (for Sunday)</entry>
91
104
</row>
92
105
<row>
93
106
<entry><literal>%w</literal></entry>
...
...
@@ -185,6 +198,11 @@
185
198
<entry>Two digit representation of the hour in 24-hour format</entry>
186
199
<entry><literal>00</literal> through <literal>23</literal></entry>
187
200
</row>
201
+
<row>
202
+
<entry><literal>%k</literal></entry>
203
+
<entry>Hour in 24-hour format, with a space preceding single digits</entry>
204
+
<entry><literal> 0</literal> through <literal>23</literal></entry>
205
+
</row>
188
206
<row>
189
207
<entry><literal>%I</literal></entry>
190
208
<entry>Two digit representation of the hour in 12-hour format</entry>
...
...
@@ -192,7 +210,7 @@
192
210
</row>
193
211
<row>
194
212
<entry><literal>%l (lower-case 'L')</literal></entry>
195
-
<entry>Hour in 12-hour format, with a space preceeding single digits</entry>
213
+
<entry>Hour in 12-hour format, with a space preceding single digits</entry>
196
214
<entry><literal> 1</literal> through <literal>12</literal></entry>
197
215
</row>
198
216
<row>
...
...
@@ -203,12 +221,17 @@
203
221
<row>
204
222
<entry><literal>%p</literal></entry>
205
223
<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>
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>
207
228
</row>
208
229
<row>
209
230
<entry><literal>%P</literal></entry>
210
231
<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>
232
+
<entry>Example: <literal>am</literal> for 00:31,
233
+
<literal>pm</literal> for 22:23. Not supported by all Operating
234
+
Systems.</entry>
212
235
</row>
213
236
<row>
214
237
<entry><literal>%r</literal></entry>
...
...
@@ -237,15 +260,15 @@
237
260
</row>
238
261
<row>
239
262
<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>
263
+
<entry>The time zone offset. Not implemented as described on
264
+
Windows. See below for more information.</entry>
265
+
<entry>Example: <literal>-0500</literal> for US Eastern Time</entry>
243
266
</row>
244
267
<row>
245
268
<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>
269
+
<entry>The time zone abbreviation. Not implemented as described on
270
+
Windows. See below for more information.</entry>
271
+
<entry>Example: <literal>EST</literal> for Eastern Time</entry>
249
272
</row>
250
273
<row>
251
274
<entry align="center"><emphasis>Time and Date Stamps</emphasis></entry>
...
...
@@ -254,7 +277,7 @@
254
277
</row>
255
278
<row>
256
279
<entry><literal>%c</literal></entry>
257
-
<entry>Preferred date and time stamp based on local</entry>
280
+
<entry>Preferred date and time stamp based on locale</entry>
258
281
<entry>Example: <literal>Tue Feb 5 00:45:10 2009</literal> for
259
282
February 5, 2009 at 12:45:10 AM</entry>
260
283
</row>
...
...
@@ -303,27 +326,32 @@
303
326
</tgroup>
304
327
</table>
305
328
</para>
306
-
<para>
307
-
Maximum length of this parameter is 1023 characters.
308
-
</para>
309
329
<warning>
310
330
<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.
331
+
Contrary to ISO-9899:1999, Sun Solaris starts with Sunday as 1. As a
332
+
result, <literal>%u</literal> may not function as described in this
333
+
manual.
313
334
</simpara>
314
335
</warning>
315
336
<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>
337
+
<para>
338
+
<emphasis>Windows only:</emphasis>
339
+
</para>
340
+
<para>
341
+
The <literal>%e</literal> modifier is not supported in the Windows
342
+
implementation of this function. To achieve this value, the
343
+
<literal>%#d</literal> modifier can be used instead. The example below
344
+
illustrates how to write a cross platform compatible function.
345
+
</para>
346
+
<para>
347
+
The <literal>%z</literal> and <literal>%Z</literal> modifiers both
348
+
return the time zone name instead of the offset or abbreviation.
349
+
</para>
322
350
</warning>
323
351
<warning>
324
352
<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.
353
+
<emphasis>macOS and musl only:</emphasis> The <literal>%P</literal> modifier
354
+
is not supported in the macOS implementation of this function.
327
355
</simpara>
328
356
</warning>
329
357
</listitem>
...
...
@@ -343,6 +371,9 @@
343
371
local time if no timestamp is given. Month and weekday names and
344
372
other language-dependent strings respect the current locale set
345
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>.
346
377
</para>
347
378
</refsect1>
348
379

...
...
@@ -371,9 +402,12 @@
371
402
</row>
372
403
</thead>
373
404
<tbody>
374
-

375
-
&date.timezone.errors.changelog;
376
-

405
+
<row>
406
+
<entry>8.0.0</entry>
407
+
<entry>
408
+
<parameter>timestamp</parameter> is nullable now.
409
+
</entry>
410
+
</row>
377
411
</tbody>
378
412
</tgroup>
379
413
</informaltable>
...
...
@@ -482,11 +516,12 @@ echo strftime($format);
482
516
</para>
483
517
<para>
484
518
<example>
485
-
<title>Display all known and unknown formats.</title>
519
+
<title>Display all known and unknown formats</title>
486
520
<programlisting role="php">
487
521
<![CDATA[
488
522
<?php
489
-
// Describe the formats.
523
+

524
+
// Describe the formats
490
525
$strftimeFormats = array(
491
526
'A' => 'A full textual representation of the day',
492
527
'B' => 'Full month name, based on the locale',
...
...
@@ -524,8 +559,8 @@ $strftimeFormats = array(
524
559
'h' => 'Abbreviated month name, based on the locale (an alias of %b)',
525
560
'i' => '',
526
561
'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',
562
+
'k' => 'Hour in 24-hour format, with a space preceding single digits',
563
+
'l' => 'Hour in 12-hour format, with a space preceding single digits',
529
564
'm' => 'Two digit representation of the month',
530
565
'n' => 'A newline character ("\n")',
531
566
'o' => '',
...
...
@@ -543,28 +578,29 @@ $strftimeFormats = array(
543
578
'%' => 'A literal percentage character ("%")',
544
579
);
545
580

546
-
// Results.
581
+
// Results
547
582
$strftimeValues = array();
548
583

549
-
// Evaluate the formats whilst suppressing any errors.
550
-
foreach($strftimeFormats as $format => $description){
551
-
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}"))) {
552
587
$strftimeValues[$format] = $value;
553
588
}
554
589
}
555
590

556
-
// Find the longest value.
591
+
// Find the longest value
557
592
$maxValueLength = 2 + max(array_map('strlen', $strftimeValues));
558
593

559
-
// Report known formats.
560
-
foreach($strftimeValues as $format => $value){
594
+
// Report known formats
595
+
foreach ($strftimeValues as $format => $value) {
561
596
echo "Known format : '{$format}' = ", str_pad("'{$value}'", $maxValueLength), " ( {$strftimeFormats[$format]} )\n";
562
597
}
563
598

564
-
// Report unknown formats.
565
-
foreach(array_diff_key($strftimeFormats, $strftimeValues) as $format => $description){
599
+
// Report unknown formats
600
+
foreach (array_diff_key($strftimeFormats, $strftimeValues) as $format => $description) {
566
601
echo "Unknown format : '{$format}' ", str_pad(' ', $maxValueLength), ($description ? " ( {$description} )" : ''), "\n";
567
602
}
603
+

568
604
?>
569
605
]]>
570
606
</programlisting>
...
...
@@ -614,8 +650,8 @@ Unknown format : 'f'
614
650
Unknown format : 'g' ( Two digit representation of the year going by ISO-8601:1988 standards (see %V) )
615
651
Unknown format : 'h' ( Abbreviated month name, based on the locale (an alias of %b) )
616
652
Unknown format : 'i'
617
-
Unknown format : 'k'
618
-
Unknown format : 'l' ( Hour in 12-hour format, with a space preceeding single digits )
653
+
Unknown format : 'k' ( Hour in 24-hour format, with a space preceding single digits )
654
+
Unknown format : 'l' ( Hour in 12-hour format, with a space preceding single digits )
619
655
Unknown format : 'n' ( A newline character ("\n") )
620
656
Unknown format : 'o'
621
657
Unknown format : 'q'
...
...
@@ -645,6 +681,8 @@ Unknown format : 'v'
645
681
&reftitle.seealso;
646
682
<para>
647
683
<simplelist>
684
+
<member><methodname>IntlDateFormatter::format</methodname></member>
685
+
<member><methodname>DateTimeInterface::format</methodname></member>
648
686
<member><link xlink:href="&url.strftime.format.designer;">Online strftime() format design tool</link></member>
649
687
<member><function>setlocale</function></member>
650
688
<member><function>mktime</function></member>
...
...
@@ -655,7 +693,6 @@ Unknown format : 'v'
655
693
</para>
656
694
</refsect1>
657
695
</refentry>
658
-

659
696
<!-- Keep this comment at the end of the file
660
697
Local variables:
661
698
mode: sgml
662
699



Translation status