reference/datetime/datetimeinterface/format.xml
ac397fd0da4d814b5a2f4ba49254f9b6093315e1
...
...
@@ -2,9 +2,9 @@
2
2
<!-- $Revision$ -->
3
3
<refentry xml:id="datetime.format" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
4
4
<refnamediv>
5
-
<refname>DateTime::format</refname>
6
-
<refname>DateTimeImmutable::format</refname>
7
5
<refname>DateTimeInterface::format</refname>
6
+
<refname>DateTimeImmutable::format</refname>
7
+
<refname>DateTime::format</refname>
8
8
<refname>date_format</refname>
9
9
<refpurpose>Returns date formatted according to given format</refpurpose>
10
10
</refnamediv>
...
...
@@ -12,20 +12,20 @@
12
12
<refsect1 role="description">
13
13
&reftitle.description;
14
14
<para>&style.oop;</para>
15
-
<methodsynopsis role="oop">
16
-
<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>
17
17
<methodparam><type>string</type><parameter>format</parameter></methodparam>
18
18
</methodsynopsis>
19
19
<methodsynopsis role="DateTimeImmutable">
20
20
<modifier>public</modifier> <type>string</type><methodname>DateTimeImmutable::format</methodname>
21
21
<methodparam><type>string</type><parameter>format</parameter></methodparam>
22
22
</methodsynopsis>
23
-
<methodsynopsis role="DateTimeInterface">
24
-
<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>
25
25
<methodparam><type>string</type><parameter>format</parameter></methodparam>
26
26
</methodsynopsis>
27
27
<para>&style.procedural;</para>
28
-
<methodsynopsis role="procedural">
28
+
<methodsynopsis>
29
29
<type>string</type><methodname>date_format</methodname>
30
30
<methodparam><type>DateTimeInterface</type><parameter>object</parameter></methodparam>
31
31
<methodparam><type>string</type><parameter>format</parameter></methodparam>
...
...
@@ -45,7 +45,7 @@
45
45
<para>
46
46
The format of the outputted date <type>string</type>. See the formatting
47
47
options below. There are also several
48
-
<link linkend="datetime.constants.types">predefined date constants</link>
48
+
<link linkend="datetimeinterface.constants.types">predefined date constants</link>
49
49
that may be used instead, so for example <constant>DATE_RSS</constant>
50
50
contains the format string <literal>'D, d M Y H:i:s'</literal>.
51
51
</para>
...
...
@@ -169,11 +169,31 @@
169
169
<entry>Examples: <literal>1999</literal> or <literal>2003</literal></entry>
170
170
</row>
171
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>
172
191
<entry><literal>Y</literal></entry>
173
192
<entry>A full numeric representation of a year, at least 4 digits,
174
193
with <literal>-</literal> for years BCE.</entry>
175
194
<entry>Examples: <literal>-0055</literal>, <literal>0787</literal>,
176
-
<literal>1999</literal>, <literal>2003</literal></entry>
195
+
<literal>1999</literal>, <literal>2003</literal>,
196
+
<literal>10191</literal></entry>
177
197
</row>
178
198
<row>
179
199
<entry><literal>y</literal></entry>
...
...
@@ -281,7 +301,7 @@
281
301
The same as <literal>P</literal>, but returns <literal>Z</literal> instead of <literal>+00:00</literal>
282
302
(available as of PHP 8.0.0)
283
303
</entry>
284
-
<entry>Example: <literal>+02:00</literal></entry>
304
+
<entry>Examples: <literal>Z</literal> or <literal>+02:00</literal></entry>
285
305
</row>
286
306
<row>
287
307
<entry><literal>T</literal></entry>
...
...
@@ -355,9 +375,10 @@
355
375
</thead>
356
376
<tbody>
357
377
<row>
358
-
<entry>8.0.0</entry>
378
+
<entry>8.2.0</entry>
359
379
<entry>
360
-
Prior to this version, &false; was returned on failure.
380
+
The format characters <literal>X</literal> and <literal>x</literal>
381
+
have been added.
361
382
</entry>
362
383
</row>
363
384
<row>
...
...
@@ -373,33 +394,86 @@
373
394

374
395
<refsect1 role="examples">
375
396
&reftitle.examples;
376
-
<example>
377
-
<title><function>DateTime::format</function> example</title>
378
-
<para>&style.oop;</para>
379
-
<programlisting role="php">
397
+
<para>
398
+
<example>
399
+
<title><function>DateTimeInterface::format</function> example</title>
400
+
<para>&style.oop;</para>
401
+
<programlisting role="php">
380
402
<![CDATA[
381
403
<?php
382
-
$date = new DateTime('2000-01-01');
404
+
$date = new DateTimeImmutable('2000-01-01');
383
405
echo $date->format('Y-m-d H:i:s');
384
406
?>
385
407
]]>
386
-
</programlisting>
387
-
<para>&style.procedural;</para>
388
-
<programlisting role="php">
408
+
</programlisting>
409
+
<para>&style.procedural;</para>
410
+
<programlisting role="php">
389
411
<![CDATA[
390
412
<?php
391
413
$date = date_create('2000-01-01');
392
414
echo date_format($date, 'Y-m-d H:i:s');
393
415
?>
394
416
]]>
395
-
</programlisting>
396
-
&example.outputs;
397
-
<screen>
417
+
</programlisting>
418
+
&example.outputs;
419
+
<screen>
398
420
<![CDATA[
399
421
2000-01-01 00:00:00
400
422
]]>
401
-
</screen>
402
-
</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>
403
477
</refsect1>
404
478

405
479
<refsect1 role="notes">
...
...
@@ -412,7 +486,7 @@ echo date_format($date, 'Y-m-d H:i:s');
412
486
<refsect1 role="seealso">
413
487
&reftitle.seealso;
414
488
<simplelist>
415
-
<member><function>date</function></member>
489
+
<member><methodname>IntlDateFormatter::format</methodname></member>
416
490
</simplelist>
417
491
</refsect1>
418
492

419
493