reference/datetime/formats.xml
7a75b854c8c52226d38397e7e8177e339fdb273f
...
...
@@ -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,52 +18,66 @@
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:
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:
67
81
<example>
68
82
<programlisting role="php">
69
83
<![CDATA[
...
...
@@ -83,50 +97,55 @@ array(1) {
83
97
]]>
84
98
</screen>
85
99
</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.
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.
93
107
<example>
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
128
</example>
115
-
</para>
116
-
</listitem>
117
-
</orderedlist>
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>
...
...
@@ -449,6 +478,11 @@ class DateTime#1 (3) {
449
478
<entry>"1978", "2008"</entry>
450
479
</row>
451
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>
485
+
<row>
452
486
<entry>Textual month (and just the month)</entry>
453
487
<entry><literal>m</literal></entry>
454
488
<entry>"March", "jun", "DEC"</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>
...
...
@@ -555,16 +594,21 @@ class DateTime#1 (3) {
555
594
<!--}}}-->
556
595

557
596
<!--Compound Formats: {{{-->
558
-
<sect1 xml:id="datetime.formats.compound">
597
+
<sect1 annotations="chunk:false" xml:id="datetime.formats.compound">
559
598
<title>Compound Formats</title>
560
599

561
600
<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>,
601
+
This page describes the different compound date/time formats in a BNF-like
602
+
syntax, that the <classname>DateTimeImmutable</classname>,
603
+
<classname>DateTime</classname>, <function>date_create</function>,
565
604
<function>date_create_immutable</function>, and
566
605
<function>strtotime</function> parser understands.
567
606
</para>
607
+
<para>
608
+
To format <classname>DateTimeImmutable</classname> and
609
+
<classname>DateTime</classname> objects, please refer to the documentation
610
+
of the <function>DateTimeInterface::format</function> method.
611
+
</para>
568
612

569
613
<table>
570
614
<title>Used Symbols</title>
...
...
@@ -779,6 +823,11 @@ class DateTime#1 (3) {
779
823
<entry>"@1215282385"</entry>
780
824
</row>
781
825
<row>
826
+
<entry>Unix Timestamp with microseconds</entry>
827
+
<entry>"@" "-"? [0-9]+ "." [0-9]{0,6}</entry>
828
+
<entry>"@1607974647.503686"</entry>
829
+
</row>
830
+
<row>
782
831
<entry>XMLRPC</entry>
783
832
<entry><literal>YY</literal> <literal>MM</literal> <literal>DD</literal> "T" <literal>hh</literal> ":" <literal>II</literal> ":" <literal>SS</literal></entry>
784
833
<entry>"20080701T22:38:07", "20080701T9:38:07"</entry>
...
...
@@ -804,7 +853,7 @@ class DateTime#1 (3) {
804
853
"W".
805
854
</para>
806
855
<para>
807
-
The "T" in the SOAP, XMRPC and WDDX formats is case-sensitive, you
856
+
The "T" in the SOAP, XMLRPC and WDDX formats is case-sensitive, you
808
857
can only use the upper case "T".
809
858
</para>
810
859
<para>
...
...
@@ -815,15 +864,20 @@ class DateTime#1 (3) {
815
864
<!--}}}-->
816
865

817
866
<!--Relative Formats: {{{-->
818
-
<sect1 xml:id="datetime.formats.relative">
867
+
<sect1 annotations="chunk:false" xml:id="datetime.formats.relative">
819
868
<title>Relative Formats</title>
820
869
<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>,
870
+
This page describes the different relative date/time formats in a BNF-like
871
+
syntax, that the <classname>DateTimeImmutable</classname>,
872
+
<classname>DateTime</classname>, <function>date_create</function>,
824
873
<function>date_create_immutable</function>, and
825
874
<function>strtotime</function> parser understands.
826
875
</para>
876
+
<para>
877
+
To format <classname>DateTimeImmutable</classname> and
878
+
<classname>DateTime</classname> objects, please refer to the documentation
879
+
of the <function>DateTimeInterface::format</function> method.
880
+
</para>
827
881

828
882
<table>
829
883
<title>Used Symbols</title>
...
...
@@ -865,9 +919,10 @@ class DateTime#1 (3) {
865
919
</row>
866
920
<row>
867
921
<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>
922
+
<entry>'ms' | 'µs' | (( 'msec' | 'millisecond' | 'µsec' | 'microsecond'
923
+
| 'usec' | 'sec' | 'second' | 'min' | 'minute' | 'hour' | 'day' |
924
+
'fortnight' | 'forthnight' | 'month' | 'year') 's'?) | 'weeks' |
925
+
<literal>daytext</literal></entry>
871
926
</row>
872
927
</tbody>
873
928
</tgroup>
...
...
@@ -954,9 +1009,12 @@ class DateTime#1 (3) {
954
1009
<entry>"+5 weeks", "12 day", "-7 weekdays"</entry>
955
1010
</row>
956
1011
<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>
1012
+
<entry>(<literal>ordinal</literal> | <literal>reltext</literal>) <literal>space</literal> <literal>unit</literal></entry>
1013
+
<entry>Handles relative time items where the value is text.
1014
+
<literal>last</literal> and <literal>previous</literal> are equivalent
1015
+
to <literal>-1</literal>, <literal>this</literal> to nothing, and
1016
+
<literal>next</literal> to <literal>+1</literal>.</entry>
1017
+
<entry>"fifth day", "second month", "last day", "previous year"</entry>
960
1018
</row>
961
1019
<row>
962
1020
<entry>'ago'</entry>
...
...
@@ -965,7 +1023,10 @@ class DateTime#1 (3) {
965
1023
</row>
966
1024
<row>
967
1025
<entry><literal>dayname</literal></entry>
968
-
<entry>Moves to the next day of this name.</entry>
1026
+
<entry>
1027
+
Moves to the next day of this name. (See <link
1028
+
linkend="datetime.formats.relative.dayname-note">note</link>)
1029
+
</entry>
969
1030
<entry>"Monday"</entry>
970
1031
</row>
971
1032
<row>
...
...
@@ -997,12 +1058,12 @@ class DateTime#1 (3) {
997
1058
the referent is the current system timestamp. However, if used in
998
1059
<function>DateTime::modify</function> or
999
1060
<function>DateTimeImmutable::modify</function>, the referent is the object
1000
-
on which the modify() method is called.
1061
+
on which the <literal>modify()</literal> method is called.
1001
1062
</para>
1002
1063
</note>
1003
1064

1004
1065
<note>
1005
-
<para>
1066
+
<para xml:id="datetime.formats.relative.dayname-note">
1006
1067
Observe the following remarks when the current day-of-week is the
1007
1068
same as the day-of-week used in the date/time string. The current
1008
1069
day-of-week could have been (re-)calculated by non-relative parts of
...
...
@@ -1135,6 +1196,13 @@ class DateTime#1 (3) {
1135
1196
</thead>
1136
1197
<tbody>
1137
1198
<row>
1199
+
<entry>8.2.0</entry>
1200
+
<entry>
1201
+
<literal>number</literal> no longer accepts multiple signs,
1202
+
e.g. <literal>+-2</literal>.
1203
+
</entry>
1204
+
</row>
1205
+
<row>
1138
1206
<entry>7.0.8</entry>
1139
1207
<entry>
1140
1208
Weeks always start on monday. Formerly, sunday would also be considered
1141
1209