reference/datetime/datetimeinterface/format.xml
ac397fd0da4d814b5a2f4ba49254f9b6093315e1
...
...
@@ -1,11 +1,10 @@
1
1
<?xml version="1.0" encoding="utf-8"?>
2
2
<!-- $Revision$ -->
3
-

4
3
<refentry xml:id="datetime.format" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
5
4
<refnamediv>
6
-
<refname>DateTime::format</refname>
7
-
<refname>DateTimeImmutable::format</refname>
8
5
<refname>DateTimeInterface::format</refname>
6
+
<refname>DateTimeImmutable::format</refname>
7
+
<refname>DateTime::format</refname>
9
8
<refname>date_format</refname>
10
9
<refpurpose>Returns date formatted according to given format</refpurpose>
11
10
</refnamediv>
...
...
@@ -13,20 +12,20 @@
13
12
<refsect1 role="description">
14
13
&reftitle.description;
15
14
<para>&style.oop;</para>
16
-
<methodsynopsis role="oop">
17
-
<modifier>public</modifier> <type>string</type><methodname>DateTime::format</methodname>
15
+
<methodsynopsis role="DateTimeInterface">
16
+
<modifier>public</modifier> <type>string</type><methodname>DateTimeInterface::format</methodname>
18
17
<methodparam><type>string</type><parameter>format</parameter></methodparam>
19
18
</methodsynopsis>
20
19
<methodsynopsis role="DateTimeImmutable">
21
20
<modifier>public</modifier> <type>string</type><methodname>DateTimeImmutable::format</methodname>
22
21
<methodparam><type>string</type><parameter>format</parameter></methodparam>
23
22
</methodsynopsis>
24
-
<methodsynopsis role="DateTimeInterface">
25
-
<modifier>public</modifier> <type>string</type><methodname>DateTimeInterface::format</methodname>
23
+
<methodsynopsis role="DateTime">
24
+
<modifier>public</modifier> <type>string</type><methodname>DateTime::format</methodname>
26
25
<methodparam><type>string</type><parameter>format</parameter></methodparam>
27
26
</methodsynopsis>
28
27
<para>&style.procedural;</para>
29
-
<methodsynopsis role="procedural">
28
+
<methodsynopsis>
30
29
<type>string</type><methodname>date_format</methodname>
31
30
<methodparam><type>DateTimeInterface</type><parameter>object</parameter></methodparam>
32
31
<methodparam><type>string</type><parameter>format</parameter></methodparam>
...
...
@@ -44,8 +43,314 @@
44
43
<term><parameter>format</parameter></term>
45
44
<listitem>
46
45
<para>
47
-
Format accepted by <function>date</function>.
46
+
The format of the outputted date <type>string</type>. See the formatting
47
+
options below. There are also several
48
+
<link linkend="datetimeinterface.constants.types">predefined date constants</link>
49
+
that may be used instead, so for example <constant>DATE_RSS</constant>
50
+
contains the format string <literal>'D, d M Y H:i:s'</literal>.
51
+
</para>
52
+
<para>
53
+
<table>
54
+
<title>The following characters are recognized in the
55
+
<parameter>format</parameter> parameter string</title>
56
+
<tgroup cols="3">
57
+
<thead>
58
+
<row>
59
+
<entry><parameter>format</parameter> character</entry>
60
+
<entry>Description</entry>
61
+
<entry>Example returned values</entry>
62
+
</row>
63
+
</thead>
64
+
<tbody>
65
+
<row>
66
+
<entry align="center"><emphasis>Day</emphasis></entry>
67
+
<entry>---</entry>
68
+
<entry>---</entry>
69
+
</row>
70
+
<row>
71
+
<entry><literal>d</literal></entry>
72
+
<entry>Day of the month, 2 digits with leading zeros</entry>
73
+
<entry><literal>01</literal> to <literal>31</literal></entry>
74
+
</row>
75
+
<row>
76
+
<entry><literal>D</literal></entry>
77
+
<entry>A textual representation of a day, three letters</entry>
78
+
<entry><literal>Mon</literal> through <literal>Sun</literal></entry>
79
+
</row>
80
+
<row>
81
+
<entry><literal>j</literal></entry>
82
+
<entry>Day of the month without leading zeros</entry>
83
+
<entry><literal>1</literal> to <literal>31</literal></entry>
84
+
</row>
85
+
<row>
86
+
<entry><literal>l</literal> (lowercase 'L')</entry>
87
+
<entry>A full textual representation of the day of the week</entry>
88
+
<entry><literal>Sunday</literal> through <literal>Saturday</literal></entry>
89
+
</row>
90
+
<row>
91
+
<entry><literal>N</literal></entry>
92
+
<entry>ISO 8601 numeric representation of the day of the week</entry>
93
+
<entry><literal>1</literal> (for Monday) through <literal>7</literal> (for Sunday)</entry>
94
+
</row>
95
+
<row>
96
+
<entry><literal>S</literal></entry>
97
+
<entry>English ordinal suffix for the day of the month, 2 characters</entry>
98
+
<entry>
99
+
<literal>st</literal>, <literal>nd</literal>, <literal>rd</literal> or
100
+
<literal>th</literal>. Works well with <literal>j</literal>
101
+
</entry>
102
+
</row>
103
+
<row>
104
+
<entry><literal>w</literal></entry>
105
+
<entry>Numeric representation of the day of the week</entry>
106
+
<entry><literal>0</literal> (for Sunday) through <literal>6</literal> (for Saturday)</entry>
107
+
</row>
108
+
<row>
109
+
<entry><literal>z</literal></entry>
110
+
<entry>The day of the year (starting from 0)</entry>
111
+
<entry><literal>0</literal> through <literal>365</literal></entry>
112
+
</row>
113
+
<row>
114
+
<entry align="center"><emphasis>Week</emphasis></entry>
115
+
<entry>---</entry>
116
+
<entry>---</entry>
117
+
</row>
118
+
<row>
119
+
<entry><literal>W</literal></entry>
120
+
<entry>ISO 8601 week number of year, weeks starting on Monday</entry>
121
+
<entry>Example: <literal>42</literal> (the 42nd week in the year)</entry>
122
+
</row>
123
+
<row>
124
+
<entry align="center"><emphasis>Month</emphasis></entry>
125
+
<entry>---</entry>
126
+
<entry>---</entry>
127
+
</row>
128
+
<row>
129
+
<entry><literal>F</literal></entry>
130
+
<entry>A full textual representation of a month, such as January or March</entry>
131
+
<entry><literal>January</literal> through <literal>December</literal></entry>
132
+
</row>
133
+
<row>
134
+
<entry><literal>m</literal></entry>
135
+
<entry>Numeric representation of a month, with leading zeros</entry>
136
+
<entry><literal>01</literal> through <literal>12</literal></entry>
137
+
</row>
138
+
<row>
139
+
<entry><literal>M</literal></entry>
140
+
<entry>A short textual representation of a month, three letters</entry>
141
+
<entry><literal>Jan</literal> through <literal>Dec</literal></entry>
142
+
</row>
143
+
<row>
144
+
<entry><literal>n</literal></entry>
145
+
<entry>Numeric representation of a month, without leading zeros</entry>
146
+
<entry><literal>1</literal> through <literal>12</literal></entry>
147
+
</row>
148
+
<row>
149
+
<entry><literal>t</literal></entry>
150
+
<entry>Number of days in the given month</entry>
151
+
<entry><literal>28</literal> through <literal>31</literal></entry>
152
+
</row>
153
+
<row>
154
+
<entry align="center"><emphasis>Year</emphasis></entry>
155
+
<entry>---</entry>
156
+
<entry>---</entry>
157
+
</row>
158
+
<row>
159
+
<entry><literal>L</literal></entry>
160
+
<entry>Whether it's a leap year</entry>
161
+
<entry><literal>1</literal> if it is a leap year, <literal>0</literal> otherwise.</entry>
162
+
</row>
163
+
<row>
164
+
<entry><literal>o</literal></entry>
165
+
<entry>ISO 8601 week-numbering year. This has the same value as
166
+
<literal>Y</literal>, except that if the ISO week number
167
+
(<literal>W</literal>) belongs to the previous or next year, that year
168
+
is used instead.</entry>
169
+
<entry>Examples: <literal>1999</literal> or <literal>2003</literal></entry>
170
+
</row>
171
+
<row>
172
+
<entry><literal>X</literal></entry>
173
+
<entry>An expanded full numeric representation of a year, at least 4 digits,
174
+
with <literal>-</literal> for years BCE, and <literal>+</literal>
175
+
for years CE.</entry>
176
+
<entry>Examples: <literal>-0055</literal>, <literal>+0787</literal>,
177
+
<literal>+1999</literal>, <literal>+10191</literal></entry>
178
+
</row>
179
+
<row>
180
+
<entry><literal>x</literal></entry>
181
+
<entry>An expanded full numeric representation if required, or a
182
+
standard full numeral representation if possible (like
183
+
<literal>Y</literal>). At least four digits. Years BCE are prefixed
184
+
with a <literal>-</literal>. Years beyond (and including)
185
+
<literal>10000</literal> are prefixed by a
186
+
<literal>+</literal>.</entry>
187
+
<entry>Examples: <literal>-0055</literal>, <literal>0787</literal>,
188
+
<literal>1999</literal>, <literal>+10191</literal></entry>
189
+
</row>
190
+
<row>
191
+
<entry><literal>Y</literal></entry>
192
+
<entry>A full numeric representation of a year, at least 4 digits,
193
+
with <literal>-</literal> for years BCE.</entry>
194
+
<entry>Examples: <literal>-0055</literal>, <literal>0787</literal>,
195
+
<literal>1999</literal>, <literal>2003</literal>,
196
+
<literal>10191</literal></entry>
197
+
</row>
198
+
<row>
199
+
<entry><literal>y</literal></entry>
200
+
<entry>A two digit representation of a year</entry>
201
+
<entry>Examples: <literal>99</literal> or <literal>03</literal></entry>
202
+
</row>
203
+
<row>
204
+
<entry align="center"><emphasis>Time</emphasis></entry>
205
+
<entry>---</entry>
206
+
<entry>---</entry>
207
+
</row>
208
+
<row>
209
+
<entry><literal>a</literal></entry>
210
+
<entry>Lowercase Ante meridiem and Post meridiem</entry>
211
+
<entry><literal>am</literal> or <literal>pm</literal></entry>
212
+
</row>
213
+
<row>
214
+
<entry><literal>A</literal></entry>
215
+
<entry>Uppercase Ante meridiem and Post meridiem</entry>
216
+
<entry><literal>AM</literal> or <literal>PM</literal></entry>
217
+
</row>
218
+
<row>
219
+
<entry><literal>B</literal></entry>
220
+
<entry>Swatch Internet time</entry>
221
+
<entry><literal>000</literal> through <literal>999</literal></entry>
222
+
</row>
223
+
<row>
224
+
<entry><literal>g</literal></entry>
225
+
<entry>12-hour format of an hour without leading zeros</entry>
226
+
<entry><literal>1</literal> through <literal>12</literal></entry>
227
+
</row>
228
+
<row>
229
+
<entry><literal>G</literal></entry>
230
+
<entry>24-hour format of an hour without leading zeros</entry>
231
+
<entry><literal>0</literal> through <literal>23</literal></entry>
232
+
</row>
233
+
<row>
234
+
<entry><literal>h</literal></entry>
235
+
<entry>12-hour format of an hour with leading zeros</entry>
236
+
<entry><literal>01</literal> through <literal>12</literal></entry>
237
+
</row>
238
+
<row>
239
+
<entry><literal>H</literal></entry>
240
+
<entry>24-hour format of an hour with leading zeros</entry>
241
+
<entry><literal>00</literal> through <literal>23</literal></entry>
242
+
</row>
243
+
<row>
244
+
<entry><literal>i</literal></entry>
245
+
<entry>Minutes with leading zeros</entry>
246
+
<entry><literal>00</literal> to <literal>59</literal></entry>
247
+
</row>
248
+
<row>
249
+
<entry><literal>s</literal></entry>
250
+
<entry>Seconds with leading zeros</entry>
251
+
<entry><literal>00</literal> through <literal>59</literal></entry>
252
+
</row>
253
+
<row>
254
+
<entry><literal>u</literal></entry>
255
+
<entry>
256
+
Microseconds. Note that
257
+
<function>date</function> will always generate
258
+
<literal>000000</literal> since it takes an <type>int</type>
259
+
parameter, whereas <methodname>DateTime::format</methodname> does
260
+
support microseconds if <classname>DateTime</classname> was
261
+
created with microseconds.
262
+
</entry>
263
+
<entry>Example: <literal>654321</literal></entry>
264
+
</row>
265
+
<row>
266
+
<entry><literal>v</literal></entry>
267
+
<entry>
268
+
Milliseconds. Same note applies as for
269
+
<literal>u</literal>.
270
+
</entry>
271
+
<entry>Example: <literal>654</literal></entry>
272
+
</row>
273
+
<row>
274
+
<entry align="center"><emphasis>Timezone</emphasis></entry>
275
+
<entry>---</entry>
276
+
<entry>---</entry>
277
+
</row>
278
+
<row>
279
+
<entry><literal>e</literal></entry>
280
+
<entry>Timezone identifier</entry>
281
+
<entry>Examples: <literal>UTC</literal>, <literal>GMT</literal>, <literal>Atlantic/Azores</literal></entry>
282
+
</row>
283
+
<row>
284
+
<entry><literal>I</literal> (capital i)</entry>
285
+
<entry>Whether or not the date is in daylight saving time</entry>
286
+
<entry><literal>1</literal> if Daylight Saving Time, <literal>0</literal> otherwise.</entry>
287
+
</row>
288
+
<row>
289
+
<entry><literal>O</literal></entry>
290
+
<entry>Difference to Greenwich time (GMT) without colon between hours and minutes</entry>
291
+
<entry>Example: <literal>+0200</literal></entry>
292
+
</row>
293
+
<row>
294
+
<entry><literal>P</literal></entry>
295
+
<entry>Difference to Greenwich time (GMT) with colon between hours and minutes</entry>
296
+
<entry>Example: <literal>+02:00</literal></entry>
297
+
</row>
298
+
<row>
299
+
<entry><literal>p</literal></entry>
300
+
<entry>
301
+
The same as <literal>P</literal>, but returns <literal>Z</literal> instead of <literal>+00:00</literal>
302
+
(available as of PHP 8.0.0)
303
+
</entry>
304
+
<entry>Examples: <literal>Z</literal> or <literal>+02:00</literal></entry>
305
+
</row>
306
+
<row>
307
+
<entry><literal>T</literal></entry>
308
+
<entry>Timezone abbreviation, if known; otherwise the GMT offset.</entry>
309
+
<entry>Examples: <literal>EST</literal>, <literal>MDT</literal>, <literal>+05</literal></entry>
310
+
</row>
311
+
<row>
312
+
<entry><literal>Z</literal></entry>
313
+
<entry>Timezone offset in seconds. The offset for timezones west of UTC is always
314
+
negative, and for those east of UTC is always positive.</entry>
315
+
<entry><literal>-43200</literal> through <literal>50400</literal></entry>
316
+
</row>
317
+
<row>
318
+
<entry align="center"><emphasis>Full Date/Time</emphasis></entry>
319
+
<entry>---</entry>
320
+
<entry>---</entry>
321
+
</row>
322
+
<row>
323
+
<entry><literal>c</literal></entry>
324
+
<entry>ISO 8601 date</entry>
325
+
<entry>2004-02-12T15:19:21+00:00</entry>
326
+
</row>
327
+
<row>
328
+
<entry><literal>r</literal></entry>
329
+
<entry><link xlink:href="&url.rfc;2822">RFC 2822</link>/<link xlink:href="&url.rfc;5322">RFC 5322</link> formatted date</entry>
330
+
<entry>Example: <literal>Thu, 21 Dec 2000 16:01:07 +0200</literal></entry>
331
+
</row>
332
+
<row>
333
+
<entry><literal>U</literal></entry>
334
+
<entry>Seconds since the Unix Epoch (January 1 1970 00:00:00 GMT)</entry>
335
+
<entry>See also <function>time</function></entry>
336
+
</row>
337
+
</tbody>
338
+
</tgroup>
339
+
</table>
340
+
</para>
341
+
<para>
342
+
Unrecognized characters in the format string will be printed
343
+
as-is. The <literal>Z</literal> format will always return
344
+
<literal>0</literal> when using <function>gmdate</function>.
48
345
</para>
346
+
<note>
347
+
<para>
348
+
Since this function only accepts <type>int</type> timestamps the
349
+
<literal>u</literal> format character is only useful when using the
350
+
<function>date_format</function> function with user based timestamps
351
+
created with <function>date_create</function>.
352
+
</para>
353
+
</note>
49
354
</listitem>
50
355
</varlistentry>
51
356
</variablelist>
...
...
@@ -54,39 +359,121 @@
54
359
<refsect1 role="returnvalues">
55
360
&reftitle.returnvalues;
56
361
<para>
57
-
Returns the formatted date string on success&return.falseforfailure;.
362
+
Returns the formatted date string on success.
58
363
</para>
59
364
</refsect1>
60
365

366
+
<refsect1 role="changelog">
367
+
&reftitle.changelog;
368
+
<informaltable>
369
+
<tgroup cols="2">
370
+
<thead>
371
+
<row>
372
+
<entry>&Version;</entry>
373
+
<entry>&Description;</entry>
374
+
</row>
375
+
</thead>
376
+
<tbody>
377
+
<row>
378
+
<entry>8.2.0</entry>
379
+
<entry>
380
+
The format characters <literal>X</literal> and <literal>x</literal>
381
+
have been added.
382
+
</entry>
383
+
</row>
384
+
<row>
385
+
<entry>8.0.0</entry>
386
+
<entry>
387
+
The format character <literal>p</literal> has been added.
388
+
</entry>
389
+
</row>
390
+
</tbody>
391
+
</tgroup>
392
+
</informaltable>
393
+
</refsect1>
394
+

61
395
<refsect1 role="examples">
62
396
&reftitle.examples;
63
-
<example>
64
-
<title><function>DateTime::format</function> example</title>
65
-
<para>&style.oop;</para>
66
-
<programlisting role="php">
397
+
<para>
398
+
<example>
399
+
<title><function>DateTimeInterface::format</function> example</title>
400
+
<para>&style.oop;</para>
401
+
<programlisting role="php">
67
402
<![CDATA[
68
403
<?php
69
-
$date = new DateTime('2000-01-01');
404
+
$date = new DateTimeImmutable('2000-01-01');
70
405
echo $date->format('Y-m-d H:i:s');
71
406
?>
72
407
]]>
73
-
</programlisting>
74
-
<para>&style.procedural;</para>
75
-
<programlisting role="php">
408
+
</programlisting>
409
+
<para>&style.procedural;</para>
410
+
<programlisting role="php">
76
411
<![CDATA[
77
412
<?php
78
413
$date = date_create('2000-01-01');
79
414
echo date_format($date, 'Y-m-d H:i:s');
80
415
?>
81
416
]]>
82
-
</programlisting>
83
-
&example.outputs;
84
-
<screen>
417
+
</programlisting>
418
+
&example.outputs;
419
+
<screen>
85
420
<![CDATA[
86
421
2000-01-01 00:00:00
87
422
]]>
88
-
</screen>
89
-
</example>
423
+
</screen>
424
+
</example>
425
+
</para>
426
+

427
+
<para>
428
+
<example>
429
+
<title>More examples</title>
430
+
<programlisting role="php">
431
+
<![CDATA[
432
+
<?php
433
+
// set the default timezone to use.
434
+
date_default_timezone_set('UTC');
435
+

436
+
// now
437
+
$date = new DateTimeImmutable();
438
+

439
+
// Prints something like: Wednesday
440
+
echo $date->format('l'), "\n";
441
+

442
+
// Prints something like: Wednesday 19th of October 2022 08:40:48 AM
443
+
echo $date->format('l jS \o\f F Y h:i:s A'), "\n";
444
+

445
+
/* use the constants in the format parameter */
446
+
// prints something like: Wed, 19 Oct 2022 08:40:48 +0000
447
+
echo $date->format(DateTimeInterface::RFC2822), "\n";
448
+
?>
449
+
]]>
450
+
</programlisting>
451
+
</example>
452
+
</para>
453
+
<para>
454
+
You can prevent a recognized character in the format string from being
455
+
expanded by escaping it with a preceding backslash. If the character with
456
+
a backslash is already a special sequence, you may need to also escape
457
+
the backslash.
458
+
<example>
459
+
<title>Escaping characters while formatting</title>
460
+
<programlisting role="php">
461
+
<![CDATA[
462
+
<?php
463
+
$date = new DateTimeImmutable();
464
+

465
+
// prints something like: Wednesday the 19th
466
+
echo $date->format('l \t\h\e jS');
467
+
?>
468
+
]]>
469
+
</programlisting>
470
+
</example>
471
+
</para>
472
+
<para>
473
+
To format dates in other languages,
474
+
<methodname>IntlDateFormatter::format</methodname>
475
+
can be used instead of <methodname>DateTimeInterface::format</methodname>.
476
+
</para>
90
477
</refsect1>
91
478

92
479
<refsect1 role="notes">
...
...
@@ -99,12 +486,11 @@ echo date_format($date, 'Y-m-d H:i:s');
99
486
<refsect1 role="seealso">
100
487
&reftitle.seealso;
101
488
<simplelist>
102
-
<member><function>date</function></member>
489
+
<member><methodname>IntlDateFormatter::format</methodname></member>
103
490
</simplelist>
104
491
</refsect1>
105
492

106
493
</refentry>
107
-

108
494
<!-- Keep this comment at the end of the file
109
495
Local variables:
110
496
mode: sgml
111
497