reference/datetime/functions/strftime.xml
5c951013ca04161992efed8b86fb40f55669958e
...
...
@@ -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">
...
...
@@ -187,8 +199,7 @@
187
199
</row>
188
200
<row>
189
201
<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>
202
+
<entry>Hour in 24-hour format, with a space preceding single digits</entry>
192
203
<entry><literal> 0</literal> through <literal>23</literal></entry>
193
204
</row>
194
205
<row>
...
...
@@ -209,12 +220,17 @@
209
220
<row>
210
221
<entry><literal>%p</literal></entry>
211
222
<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>
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>
213
227
</row>
214
228
<row>
215
229
<entry><literal>%P</literal></entry>
216
230
<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>
231
+
<entry>Example: <literal>am</literal> for 00:31,
232
+
<literal>pm</literal> for 22:23. Not supported by all Operating
233
+
Systems.</entry>
218
234
</row>
219
235
<row>
220
236
<entry><literal>%r</literal></entry>
...
...
@@ -309,9 +325,6 @@
309
325
</tgroup>
310
326
</table>
311
327
</para>
312
-
<para>
313
-
Maximum length of this parameter is 1023 characters.
314
-
</para>
315
328
<warning>
316
329
<simpara>
317
330
Contrary to ISO-9899:1999, Sun Solaris starts with Sunday as 1. As a
...
...
@@ -336,8 +349,8 @@
336
349
</warning>
337
350
<warning>
338
351
<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.
352
+
<emphasis>macOS and musl only:</emphasis> The <literal>%P</literal> modifier
353
+
is not supported in the macOS implementation of this function.
341
354
</simpara>
342
355
</warning>
343
356
</listitem>
...
...
@@ -357,6 +370,9 @@
357
370
local time if no timestamp is given. Month and weekday names and
358
371
other language-dependent strings respect the current locale set
359
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>.
360
376
</para>
361
377
</refsect1>
362
378

...
...
@@ -385,9 +401,12 @@
385
401
</row>
386
402
</thead>
387
403
<tbody>
388
-

389
-
&date.timezone.errors.changelog;
390
-

404
+
<row>
405
+
<entry>8.0.0</entry>
406
+
<entry>
407
+
<parameter>timestamp</parameter> is nullable now.
408
+
</entry>
409
+
</row>
391
410
</tbody>
392
411
</tgroup>
393
412
</informaltable>
...
...
@@ -659,6 +678,8 @@ Unknown format : 'v'
659
678
&reftitle.seealso;
660
679
<para>
661
680
<simplelist>
681
+
<member><methodname>IntlDateFormatter::format</methodname></member>
682
+
<member><methodname>DateTimeInterface::format</methodname></member>
662
683
<member><link xlink:href="&url.strftime.format.designer;">Online strftime() format design tool</link></member>
663
684
<member><function>setlocale</function></member>
664
685
<member><function>mktime</function></member>
...
...
@@ -669,7 +690,6 @@ Unknown format : 'v'
669
690
</para>
670
691
</refsect1>
671
692
</refentry>
672
-

673
693
<!-- Keep this comment at the end of the file
674
694
Local variables:
675
695
mode: sgml
676
696