reference/datetime/formats.xml
64dc79d6c9710dddf196aa28e3c5f63b562e7aef
...
...
@@ -4,7 +4,7 @@
4
4
<title>Supported Date and Time Formats</title>
5
5

6
6
<para>
7
-
This section describes all the different formats that the
7
+
This section describes all the different formats in a BNF-like format, that the
8
8
<classname>DateTimeImmutable</classname>, <classname>DateTime</classname>,
9
9
<function>date_create_immutable</function>,
10
10
<function>date_create</function>, <function>date_parse</function>, and
...
...
@@ -18,53 +18,67 @@
18
18
double quotes are case-sensitive (<literal>"T"</literal> is only
19
19
<literal>T</literal>).
20
20
</para>
21
+
<para>
22
+
To format <classname>DateTimeImmutable</classname> and
23
+
<classname>DateTime</classname> objects, please refer to the documentation
24
+
of the <function>DateTimeInterface::format</function> method.
25
+
</para>
21
26

22
27
<para>
23
28
A general set of rules should be taken into account.
24
29
</para>
25
-
<orderedlist>
26
-
<listitem>
27
-
<simpara>
28
-
The parser, allows for each unit (year, month, day, hour, minute, second)
29
-
the full range of values. For a year that's just 4 digits, for a month
30
-
that's 0-12, day is 0-31 and for hour and minute it's 0-59.
31
-
</simpara>
32
-
</listitem>
33
-
<listitem>
34
-
<simpara>
35
-
60 is allowed for seconds, as sometimes date strings with that
36
-
leapsecond do show up. But PHP implements Unix time where "60" is not
37
-
a valid second number and hence it overflows.
38
-
</simpara>
39
-
</listitem>
40
-
<listitem>
41
-
<simpara>
42
-
<function>strtotime</function> returns false if any number is outside of
30
+
<orderedlist>
31
+
<listitem>
32
+
<simpara>
33
+
The parser, allows for each unit (year, month, day, hour, minute, second)
34
+
the full range of values. For a year that's just 4 digits, for a month
35
+
that's 0-12, day is 0-31, hour is 0-24, and minute is 0-59.
36
+
</simpara>
37
+
</listitem>
38
+
<listitem>
39
+
<simpara>
40
+
60 is allowed for seconds, as sometimes date strings with that
41
+
leapsecond do show up. But PHP implements Unix time where "60" is not
42
+
a valid second number and hence it overflows.
43
+
</simpara>
44
+
</listitem>
45
+
<listitem>
46
+
<simpara>
47
+
<function>strtotime</function> returns &false; if any number is outside of
43
48
the ranges, and <function>DateTimeImmutable::__construct</function> throws
44
49
an exception.
45
-
</simpara>
46
-
</listitem>
47
-
<listitem>
48
-
<simpara>
49
-
If a string contains a date, all time elements are reset to 0.
50
-
</simpara>
51
-
</listitem>
52
-
<listitem>
53
-
<simpara>
54
-
All less-significant time elements are reset to 0 if any part of a time is
55
-
present in the given string.
56
-
</simpara>
57
-
</listitem>
58
-
<listitem>
59
-
<simpara>
60
-
The parser is dumb, and doesn't do any checks to make it faster (and
61
-
more generic).
62
-
</simpara>
63
-
</listitem>
64
-
<listitem>
65
-
<para>
66
-
There is an additional check if you pass in an invalid date:
67
-
<example>
50
+
</simpara>
51
+
</listitem>
52
+
<listitem>
53
+
<simpara>
54
+
If a string contains a date, all time elements are reset to 0.
55
+
</simpara>
56
+
</listitem>
57
+
<listitem>
58
+
<simpara>
59
+
All less-significant time elements are reset to 0 if any part of a time is
60
+
present in the given string.
61
+
</simpara>
62
+
</listitem>
63
+
<listitem>
64
+
<simpara>
65
+
The parser is dumb, and doesn't do any checks to make it faster (and
66
+
more generic).
67
+
</simpara>
68
+
</listitem>
69
+
<listitem>
70
+
<simpara>
71
+
Besides rules for individual time elements, the parser also understand
72
+
more specific <link linkend="datetime.formats.compound">compound
73
+
formats</link>, such as parsing Unix timestamps
74
+
(<literal>@1690388256</literal>) and ISO Weekdates
75
+
(<literal>2008-W28-3</literal>).
76
+
</simpara>
77
+
</listitem>
78
+
<listitem>
79
+
<para>
80
+
There is an additional check if an invalid date is provided:
81
+
<informalexample>
68
82
<programlisting role="php">
69
83
<![CDATA[
70
84
<?php
...
...
@@ -82,51 +96,56 @@ array(1) {
82
96
}
83
97
]]>
84
98
</screen>
85
-
</example>
86
-
</para>
87
-
</listitem>
88
-
<listitem>
89
-
<para>
90
-
It is already possible to handle the edge cases, but then you need to use
91
-
<function>DateTimeImmutable::createFromFormat</function>, and
92
-
supply the right format.
93
-
<example>
99
+
</informalexample>
100
+
</para>
101
+
</listitem>
102
+
<listitem>
103
+
<para>
104
+
It is already possible to handle the edge cases, but then
105
+
<function>DateTimeImmutable::createFromFormat</function> must be used
106
+
while supplying the correct format.
107
+
<informalexample>
94
108
<programlisting role="php">
95
109
<![CDATA[
96
110
<?php
97
-
$res = DateImmutable::createFromFormat("Y-m-d", "2015-09-34");
111
+
$res = DateTimeImmutable::createFromFormat("Y-m-d", "2015-09-34");
98
112
var_dump($res);
99
113
]]>
100
114
</programlisting>
101
115
&example.outputs;
102
116
<screen>
103
117
<![CDATA[
104
-
class DateTime#1 (3) {
105
-
public $date =>
118
+
object(DateTimeImmutable)#1 (3) {
119
+
["date"]=>
106
120
string(26) "2015-10-04 17:24:43.000000"
107
-
public $timezone_type =>
121
+
["timezone_type"]=>
108
122
int(3)
109
-
public $timezone =>
123
+
["timezone"]=>
110
124
string(13) "Europe/London"
111
125
}
112
126
]]>
113
127
</screen>
114
-
</example>
115
-
</para>
116
-
</listitem>
117
-
</orderedlist>
128
+
</informalexample>
129
+
</para>
130
+
</listitem>
131
+
</orderedlist>
118
132

119
133
<!--Time Formats: {{{-->
120
-
<sect1 xml:id="datetime.formats.time">
134
+
<sect1 annotations="chunk:false" xml:id="datetime.formats.time">
121
135
<title>Time Formats</title>
122
136

123
137
<para>
124
-
This page describes the different date/time formats that the
125
-
<classname>DateTimeImmutable</classname>, <classname>DateTime</classname>,
126
-
<function>date_create</function>,
138
+
This page describes the different date/time formats in a BNF-like syntax,
139
+
that the <classname>DateTimeImmutable</classname>,
140
+
<classname>DateTime</classname>, <function>date_create</function>,
127
141
<function>date_create_immutable</function>, and
128
142
<function>strtotime</function> parser understands.
129
143
</para>
144
+
<para>
145
+
To format <classname>DateTimeImmutable</classname> and
146
+
<classname>DateTime</classname> objects, please refer to the documentation
147
+
of the <function>DateTimeInterface::format</function> method.
148
+
</para>
130
149

131
150
<table>
132
151
<title>Used Symbols</title>
...
...
@@ -276,16 +295,21 @@ class DateTime#1 (3) {
276
295
<!--}}}-->
277
296

278
297
<!--Date Formats: {{{-->
279
-
<sect1 xml:id="datetime.formats.date">
298
+
<sect1 annotations="chunk:false" xml:id="datetime.formats.date">
280
299
<title>Date Formats</title>
281
300

282
301
<para>
283
-
This page describes the different date formats that the
284
-
<classname>DateTimeImmutable</classname>, <classname>DateTime</classname>,
285
-
<function>date_create</function>,
302
+
This page describes the different date formats in a BNF-like syntax, that
303
+
the <classname>DateTimeImmutable</classname>,
304
+
<classname>DateTime</classname>, <function>date_create</function>,
286
305
<function>date_create_immutable</function>, and
287
306
<function>strtotime</function> parser understands.
288
307
</para>
308
+
<para>
309
+
To format <classname>DateTimeImmutable</classname> and
310
+
<classname>DateTime</classname> objects, please refer to the documentation
311
+
of the <function>DateTimeInterface::format</function> method.
312
+
</para>
289
313

290
314
<table>
291
315
<title>Used Symbols</title>
...
...
@@ -353,6 +377,11 @@ class DateTime#1 (3) {
353
377
<entry>[0-9]{4}</entry>
354
378
<entry>"2000", "2008", "1978"</entry>
355
379
</row>
380
+
<row>
381
+
<entry><literal>YYY</literal></entry>
382
+
<entry>[0-9]{5,19}</entry>
383
+
<entry>"81412", "20192"</entry>
384
+
</row>
356
385
</tbody>
357
386
</tgroup>
358
387
</table>
...
...
@@ -448,6 +477,11 @@ class DateTime#1 (3) {
448
477
<entry><literal>YY</literal></entry>
449
478
<entry>"1978", "2008"</entry>
450
479
</row>
480
+
<row>
481
+
<entry>Year (expanded, 5-19 digits with sign)</entry>
482
+
<entry>[+-] <literal>YYY</literal></entry>
483
+
<entry>"-81120", "+20192"</entry>
484
+
</row>
451
485
<row>
452
486
<entry>Textual month (and just the month)</entry>
453
487
<entry><literal>m</literal></entry>
...
...
@@ -488,6 +522,11 @@ class DateTime#1 (3) {
488
522
<entry>[+-]? <literal>YY</literal> "-" <literal>MM</literal> "-" <literal>DD</literal></entry>
489
523
<entry>"-0002-07-26", "+1978-04-17", "1814-05-17"</entry>
490
524
</row>
525
+
<row>
526
+
<entry>Five+ digit year with required sign, month and day</entry>
527
+
<entry>[+-] <literal>YYY</literal> "-" <literal>MM</literal> "-" <literal>DD</literal></entry>
528
+
<entry>"-81120-02-26", "+20192-04-17"</entry>
529
+
</row>
491
530
</tbody>
492
531
</tgroup>
493
532
</table>
...
...
@@ -517,9 +556,15 @@ class DateTime#1 (3) {
517
556

518
557
<note>
519
558
<para>
520
-
The "Year (and just the year)" format only works if a time string
521
-
has already been found -- otherwise this format is recognised as
522
-
<literal>HH</literal> <literal>MM</literal>.
559
+
The "Year (and just the year)" format only reliably works if a time string
560
+
has already been found. Otherwise, if the four digit year matches
561
+
<literal>HH</literal> <literal>MM</literal> then these two date elements
562
+
are set instead.
563
+
</para>
564
+
<para>
565
+
To consistently parse just a year, use
566
+
<function>DateTimeImmutable::createFromFormat</function> with the
567
+
<literal>Y</literal> specifier.
523
568
</para>
524
569
</note>
525
570

...
...
@@ -555,16 +600,21 @@ class DateTime#1 (3) {
555
600
<!--}}}-->
556
601

557
602
<!--Compound Formats: {{{-->
558
-
<sect1 xml:id="datetime.formats.compound">
603
+
<sect1 annotations="chunk:false" xml:id="datetime.formats.compound">
559
604
<title>Compound Formats</title>
560
605

561
606
<para>
562
-
This page describes the different compound date/time formats that the
563
-
<classname>DateTimeImmutable</classname>, <classname>DateTime</classname>,
564
-
<function>date_create</function>,
607
+
This page describes the different compound date/time formats in a BNF-like
608
+
syntax, that the <classname>DateTimeImmutable</classname>,
609
+
<classname>DateTime</classname>, <function>date_create</function>,
565
610
<function>date_create_immutable</function>, and
566
611
<function>strtotime</function> parser understands.
567
612
</para>
613
+
<para>
614
+
To format <classname>DateTimeImmutable</classname> and
615
+
<classname>DateTime</classname> objects, please refer to the documentation
616
+
of the <function>DateTimeInterface::format</function> method.
617
+
</para>
568
618

569
619
<table>
570
620
<title>Used Symbols</title>
...
...
@@ -778,6 +828,11 @@ class DateTime#1 (3) {
778
828
<entry>"@" "-"? [0-9]+</entry>
779
829
<entry>"@1215282385"</entry>
780
830
</row>
831
+
<row>
832
+
<entry>Unix Timestamp with microseconds</entry>
833
+
<entry>"@" "-"? [0-9]+ "." [0-9]{0,6}</entry>
834
+
<entry>"@1607974647.503686"</entry>
835
+
</row>
781
836
<row>
782
837
<entry>XMLRPC</entry>
783
838
<entry><literal>YY</literal> <literal>MM</literal> <literal>DD</literal> "T" <literal>hh</literal> ":" <literal>II</literal> ":" <literal>SS</literal></entry>
...
...
@@ -804,7 +859,7 @@ class DateTime#1 (3) {
804
859
"W".
805
860
</para>
806
861
<para>
807
-
The "T" in the SOAP, XMRPC and WDDX formats is case-sensitive, you
862
+
The "T" in the SOAP, XMLRPC and WDDX formats is case-sensitive, you
808
863
can only use the upper case "T".
809
864
</para>
810
865
<para>
...
...
@@ -815,15 +870,20 @@ class DateTime#1 (3) {
815
870
<!--}}}-->
816
871

817
872
<!--Relative Formats: {{{-->
818
-
<sect1 xml:id="datetime.formats.relative">
873
+
<sect1 annotations="chunk:false" xml:id="datetime.formats.relative">
819
874
<title>Relative Formats</title>
820
875
<para>
821
-
This page describes the different relative date/time formats that the
822
-
<classname>DateTimeImmutable</classname>, <classname>DateTime</classname>,
823
-
<function>date_create</function>,
876
+
This page describes the different relative date/time formats in a BNF-like
877
+
syntax, that the <classname>DateTimeImmutable</classname>,
878
+
<classname>DateTime</classname>, <function>date_create</function>,
824
879
<function>date_create_immutable</function>, and
825
880
<function>strtotime</function> parser understands.
826
881
</para>
882
+
<para>
883
+
To format <classname>DateTimeImmutable</classname> and
884
+
<classname>DateTime</classname> objects, please refer to the documentation
885
+
of the <function>DateTimeInterface::format</function> method.
886
+
</para>
827
887

828
888
<table>
829
889
<title>Used Symbols</title>
...
...
@@ -865,9 +925,10 @@ class DateTime#1 (3) {
865
925
</row>
866
926
<row>
867
927
<entry><literal>unit</literal></entry>
868
-
<entry>(('sec' | 'second' | 'min' | 'minute' | 'hour' | 'day' |
869
-
'fortnight' | 'forthnight' | 'month' | 'year') 's'?) | 'weeks' |
870
-
<literal>daytext</literal></entry>
928
+
<entry>'ms' | 'µs' | (( 'msec' | 'millisecond' | 'µsec' | 'microsecond'
929
+
| 'usec' | 'sec' | 'second' | 'min' | 'minute' | 'hour' | 'day' |
930
+
'fortnight' | 'forthnight' | 'month' | 'year') 's'?) | 'weeks' |
931
+
<literal>daytext</literal></entry>
871
932
</row>
872
933
</tbody>
873
934
</tgroup>
...
...
@@ -954,9 +1015,12 @@ class DateTime#1 (3) {
954
1015
<entry>"+5 weeks", "12 day", "-7 weekdays"</entry>
955
1016
</row>
956
1017
<row>
957
-
<entry><literal>ordinal</literal> <literal>space</literal> <literal>unit</literal></entry>
958
-
<entry>Handles relative time items where the value is text.</entry>
959
-
<entry>"fifth day", "second month"</entry>
1018
+
<entry>(<literal>ordinal</literal> | <literal>reltext</literal>) <literal>space</literal> <literal>unit</literal></entry>
1019
+
<entry>Handles relative time items where the value is text.
1020
+
<literal>last</literal> and <literal>previous</literal> are equivalent
1021
+
to <literal>-1</literal>, <literal>this</literal> to nothing, and
1022
+
<literal>next</literal> to <literal>+1</literal>.</entry>
1023
+
<entry>"fifth day", "second month", "last day", "previous year"</entry>
960
1024
</row>
961
1025
<row>
962
1026
<entry>'ago'</entry>
...
...
@@ -965,7 +1029,10 @@ class DateTime#1 (3) {
965
1029
</row>
966
1030
<row>
967
1031
<entry><literal>dayname</literal></entry>
968
-
<entry>Moves to the next day of this name.</entry>
1032
+
<entry>
1033
+
Moves to the next day of this name. (See <link
1034
+
linkend="datetime.formats.relative.dayname-note">note</link>)
1035
+
</entry>
969
1036
<entry>"Monday"</entry>
970
1037
</row>
971
1038
<row>
...
...
@@ -997,12 +1064,12 @@ class DateTime#1 (3) {
997
1064
the referent is the current system timestamp. However, if used in
998
1065
<function>DateTime::modify</function> or
999
1066
<function>DateTimeImmutable::modify</function>, the referent is the object
1000
-
on which the modify() method is called.
1067
+
on which the <literal>modify()</literal> method is called.
1001
1068
</para>
1002
1069
</note>
1003
1070

1004
1071
<note>
1005
-
<para>
1072
+
<para xml:id="datetime.formats.relative.dayname-note">
1006
1073
Observe the following remarks when the current day-of-week is the
1007
1074
same as the day-of-week used in the date/time string. The current
1008
1075
day-of-week could have been (re-)calculated by non-relative parts of
...
...
@@ -1134,6 +1201,21 @@ class DateTime#1 (3) {
1134
1201
</row>
1135
1202
</thead>
1136
1203
<tbody>
1204
+
<row>
1205
+
<entry>8.4.0</entry>
1206
+
<entry>
1207
+
<literal>number</literal> now again accepts a plus sign followed by a
1208
+
minus sign, e.g. <literal>+-2</literal>, and other combinations of
1209
+
multiple signs.
1210
+
</entry>
1211
+
</row>
1212
+
<row>
1213
+
<entry>8.2.0</entry>
1214
+
<entry>
1215
+
<literal>number</literal> no longer accepts a plus sign followed by a
1216
+
minus sign, e.g. <literal>+-2</literal>.
1217
+
</entry>
1218
+
</row>
1137
1219
<row>
1138
1220
<entry>7.0.8</entry>
1139
1221
<entry>
1140
1222



Translation status