reference/datetime/datetimeinterface.xml
9eb4a46bba05da229be4c8f7a3cb64702e1a2f95
...
...
@@ -1,6 +1,5 @@
1
1
<?xml version="1.0" encoding="utf-8"?>
2
2
<!-- $Revision$ -->
3
-

4
3
<phpdoc:classref xml:id="class.datetimeinterface" xmlns:phpdoc="http://php.net/ns/phpdoc" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
5
4

6
5
<title>The DateTimeInterface interface</title>
...
...
@@ -12,114 +11,146 @@
12
11
<section xml:id="datetimeinterface.intro">
13
12
&reftitle.intro;
14
13
<para>
15
-
DateTimeInterface is meant so that both DateTime and DateTimeImmutable can
16
-
be type hinted for. It is not possible to implement this interface with
17
-
userland classes.
14
+
<interfacename>DateTimeInterface</interfacename> was created
15
+
so that parameter, return, or property type declarations may accept either
16
+
<classname>DateTimeImmutable</classname> or <classname>DateTime</classname>
17
+
as a value. It is not possible to
18
+
implement this interface with userland classes.
19
+
</para>
20
+
<para>
21
+
Common constants that allow for formatting
22
+
<classname>DateTimeImmutable</classname> or
23
+
<classname>DateTime</classname> objects through
24
+
<methodname>DateTimeImmutable::format</methodname> and
25
+
<methodname>DateTime::format</methodname> are also defined on this
26
+
interface.
18
27
</para>
19
28
</section>
20
29
<!-- }}} -->
21
30

22
31
<section xml:id="datetimeinterface.synopsis">
23
-
&reftitle.classsynopsis;
32
+
&reftitle.interfacesynopsis;
24
33

25
34
<!-- {{{ Synopsis -->
26
-
<classsynopsis>
27
-
<ooclass><classname>DateTimeInterface</classname></ooclass>
28
-

29
-
<!-- {{{ Class synopsis -->
30
-
<classsynopsisinfo>
31
-
<ooclass>
32
-
<classname>DateTimeInterface</classname>
33
-
</ooclass>
34
-
</classsynopsisinfo>
35
-
<!-- }}} -->
35
+
<classsynopsis class="interface">
36
+
<oointerface>
37
+
<interfacename>DateTimeInterface</interfacename>
38
+
</oointerface>
36
39

37
40
<classsynopsisinfo role="comment">&Constants;</classsynopsisinfo>
38
41
<fieldsynopsis>
42
+
<modifier>public</modifier>
39
43
<modifier>const</modifier>
40
44
<type>string</type>
41
-
<varname linkend="datetime.constants.atom">DateTimeInterface::ATOM</varname>
42
-
<initializer>"Y-m-d\TH:i:sP"</initializer>
45
+
<varname linkend="datetimeinterface.constants.atom">DateTimeInterface::ATOM</varname>
46
+
<initializer>"Y-m-d\\TH:i:sP"</initializer>
43
47
</fieldsynopsis>
44
48
<fieldsynopsis>
49
+
<modifier>public</modifier>
45
50
<modifier>const</modifier>
46
51
<type>string</type>
47
-
<varname linkend="datetime.constants.cookie">DateTimeInterface::COOKIE</varname>
52
+
<varname linkend="datetimeinterface.constants.cookie">DateTimeInterface::COOKIE</varname>
48
53
<initializer>"l, d-M-Y H:i:s T"</initializer>
49
54
</fieldsynopsis>
50
55
<fieldsynopsis>
56
+
<modifier>public</modifier>
57
+
<modifier>const</modifier>
58
+
<type>string</type>
59
+
<varname linkend="datetimeinterface.constants.iso8601">DateTimeInterface::ISO8601</varname>
60
+
<initializer>"Y-m-d\\TH:i:sO"</initializer>
61
+
</fieldsynopsis>
62
+
<fieldsynopsis>
63
+
<modifier>public</modifier>
51
64
<modifier>const</modifier>
52
65
<type>string</type>
53
-
<varname linkend="datetime.constants.iso8601">DateTimeInterface::ISO8601</varname>
54
-
<initializer>"Y-m-d\TH:i:sO"</initializer>
66
+
<varname linkend="datetimeinterface.constants.iso8601-expanded">DateTimeInterface::ISO8601_EXPANDED</varname>
67
+
<initializer>"X-m-d\\TH:i:sP"</initializer>
55
68
</fieldsynopsis>
56
69
<fieldsynopsis>
70
+
<modifier>public</modifier>
57
71
<modifier>const</modifier>
58
72
<type>string</type>
59
-
<varname linkend="datetime.constants.rfc822">DateTimeInterface::RFC822</varname>
73
+
<varname linkend="datetimeinterface.constants.rfc822">DateTimeInterface::RFC822</varname>
60
74
<initializer>"D, d M y H:i:s O"</initializer>
61
75
</fieldsynopsis>
62
76
<fieldsynopsis>
77
+
<modifier>public</modifier>
63
78
<modifier>const</modifier>
64
79
<type>string</type>
65
-
<varname linkend="datetime.constants.rfc850">DateTimeInterface::RFC850</varname>
80
+
<varname linkend="datetimeinterface.constants.rfc850">DateTimeInterface::RFC850</varname>
66
81
<initializer>"l, d-M-y H:i:s T"</initializer>
67
82
</fieldsynopsis>
68
83
<fieldsynopsis>
84
+
<modifier>public</modifier>
69
85
<modifier>const</modifier>
70
86
<type>string</type>
71
-
<varname linkend="datetime.constants.rfc1036">DateTimeInterface::RFC1036</varname>
87
+
<varname linkend="datetimeinterface.constants.rfc1036">DateTimeInterface::RFC1036</varname>
72
88
<initializer>"D, d M y H:i:s O"</initializer>
73
89
</fieldsynopsis>
74
90
<fieldsynopsis>
91
+
<modifier>public</modifier>
75
92
<modifier>const</modifier>
76
93
<type>string</type>
77
-
<varname linkend="datetime.constants.rfc1123">DateTimeInterface::RFC1123</varname>
94
+
<varname linkend="datetimeinterface.constants.rfc1123">DateTimeInterface::RFC1123</varname>
78
95
<initializer>"D, d M Y H:i:s O"</initializer>
79
96
</fieldsynopsis>
80
97
<fieldsynopsis>
98
+
<modifier>public</modifier>
99
+
<modifier>const</modifier>
100
+
<type>string</type>
101
+
<varname linkend="datetimeinterface.constants.rfc7231">DateTimeInterface::RFC7231</varname>
102
+
<initializer>"D, d M Y H:i:s \\G\\M\\T"</initializer>
103
+
</fieldsynopsis>
104
+
<fieldsynopsis>
105
+
<modifier>public</modifier>
81
106
<modifier>const</modifier>
82
107
<type>string</type>
83
-
<varname linkend="datetime.constants.rfc2822">DateTimeInterface::RFC2822</varname>
108
+
<varname linkend="datetimeinterface.constants.rfc2822">DateTimeInterface::RFC2822</varname>
84
109
<initializer>"D, d M Y H:i:s O"</initializer>
85
110
</fieldsynopsis>
86
111
<fieldsynopsis>
112
+
<modifier>public</modifier>
87
113
<modifier>const</modifier>
88
114
<type>string</type>
89
-
<varname linkend="datetime.constants.rfc3339">DateTimeInterface::RFC3339</varname>
90
-
<initializer>"Y-m-d\TH:i:sP"</initializer>
115
+
<varname linkend="datetimeinterface.constants.rfc3339">DateTimeInterface::RFC3339</varname>
116
+
<initializer>"Y-m-d\\TH:i:sP"</initializer>
91
117
</fieldsynopsis>
92
118
<fieldsynopsis>
119
+
<modifier>public</modifier>
93
120
<modifier>const</modifier>
94
121
<type>string</type>
95
-
<varname linkend="datetime.constants.rfc3339_extended">DateTimeInterface::RFC3339_EXTENDED</varname>
96
-
<initializer>"Y-m-d\TH:i:s.vP"</initializer>
122
+
<varname linkend="datetimeinterface.constants.rfc3339-extended">DateTimeInterface::RFC3339_EXTENDED</varname>
123
+
<initializer>"Y-m-d\\TH:i:s.vP"</initializer>
97
124
</fieldsynopsis>
98
125
<fieldsynopsis>
126
+
<modifier>public</modifier>
99
127
<modifier>const</modifier>
100
128
<type>string</type>
101
-
<varname linkend="datetime.constants.rss">DateTimeInterface::RSS</varname>
129
+
<varname linkend="datetimeinterface.constants.rss">DateTimeInterface::RSS</varname>
102
130
<initializer>"D, d M Y H:i:s O"</initializer>
103
131
</fieldsynopsis>
104
132
<fieldsynopsis>
133
+
<modifier>public</modifier>
105
134
<modifier>const</modifier>
106
135
<type>string</type>
107
-
<varname linkend="datetime.constants.w3c">DateTimeInterface::W3C</varname>
108
-
<initializer>"Y-m-d\TH:i:sP"</initializer>
136
+
<varname linkend="datetimeinterface.constants.w3c">DateTimeInterface::W3C</varname>
137
+
<initializer>"Y-m-d\\TH:i:sP"</initializer>
109
138
</fieldsynopsis>
110
139

111
140
<classsynopsisinfo role="comment">&Methods;</classsynopsisinfo>
112
-
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.datetimeinterface')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[@role='DateTimeInterface'])" />
141
+
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.datetimeinterface')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[@role='DateTimeInterface'])">
142
+
<xi:fallback/>
143
+
</xi:include>
113
144
</classsynopsis>
114
145
<!-- }}} -->
115
146

116
147
</section>
117
148

118
149
<!-- {{{ DateTimeInterface constants -->
119
-
<section xml:id="datetime.constants.types">
150
+
<section xml:id="datetimeinterface.constants.types">
120
151
&reftitle.constants;
121
152
<variablelist>
122
-
<varlistentry xml:id="datetime.constants.atom">
153
+
<varlistentry xml:id="datetimeinterface.constants.atom">
123
154
<term><constant>DateTimeInterface::ATOM</constant></term>
124
155
<term><constant>DATE_ATOM</constant></term>
125
156
<listitem>
...
...
@@ -129,7 +160,7 @@
129
160
</listitem>
130
161
</varlistentry>
131
162

132
-
<varlistentry xml:id="datetime.constants.cookie">
163
+
<varlistentry xml:id="datetimeinterface.constants.cookie">
133
164
<term><constant>DateTimeInterface::COOKIE</constant></term>
134
165
<term><constant>DATE_COOKIE</constant></term>
135
166
<listitem>
...
...
@@ -139,7 +170,7 @@
139
170
</listitem>
140
171
</varlistentry>
141
172

142
-
<varlistentry xml:id="datetime.constants.iso8601">
173
+
<varlistentry xml:id="datetimeinterface.constants.iso8601">
143
174
<term><constant>DateTimeInterface::ISO8601</constant></term>
144
175
<term><constant>DATE_ISO8601</constant></term>
145
176
<listitem>
...
...
@@ -149,15 +180,34 @@
149
180
<note>
150
181
<simpara>
151
182
This format is not compatible with ISO-8601, but is left this way for
152
-
backward compatibility reasons. Use <constant>DateTime::ATOM</constant>
153
-
or <constant>DATE_ATOM</constant> for compatibility with ISO-8601
154
-
instead.
183
+
backward compatibility reasons. Use
184
+
<constant>DateTimeInterface::ISO8601_EXPANDED</constant>,
185
+
<constant>DateTimeInterface::ATOM</constant> for compatibility with ISO-8601
186
+
instead. (ref ISO8601:2004 section 4.3.3 clause d)
187
+
</simpara>
188
+
</note>
189
+
</listitem>
190
+
</varlistentry>
191
+

192
+
<varlistentry xml:id="datetimeinterface.constants.iso8601-expanded">
193
+
<term><constant>DateTimeInterface::ISO8601_EXPANDED</constant></term>
194
+
<term><constant>DATE_ISO8601_EXPANDED</constant></term>
195
+
<listitem>
196
+
<simpara>
197
+
ISO-8601 Expanded (example: +10191-07-26T08:59:52+01:00)
198
+
</simpara>
199
+
<note>
200
+
<simpara>
201
+
This format allows for year ranges outside of ISO-8601's normal range
202
+
of <literal>0000</literal>-<literal>9999</literal> by always
203
+
including a sign character. It also addresses that that timezone part
204
+
(<literal>+01:00</literal>) is compatible with ISO-8601.
155
205
</simpara>
156
206
</note>
157
207
</listitem>
158
208
</varlistentry>
159
209

160
-
<varlistentry xml:id="datetime.constants.rfc822">
210
+
<varlistentry xml:id="datetimeinterface.constants.rfc822">
161
211
<term><constant>DateTimeInterface::RFC822</constant></term>
162
212
<term><constant>DATE_RFC822</constant></term>
163
213
<listitem>
...
...
@@ -167,7 +217,7 @@
167
217
</listitem>
168
218
</varlistentry>
169
219

170
-
<varlistentry xml:id="datetime.constants.rfc850">
220
+
<varlistentry xml:id="datetimeinterface.constants.rfc850">
171
221
<term><constant>DateTimeInterface::RFC850</constant></term>
172
222
<term><constant>DATE_RFC850</constant></term>
173
223
<listitem>
...
...
@@ -177,7 +227,7 @@
177
227
</listitem>
178
228
</varlistentry>
179
229

180
-
<varlistentry xml:id="datetime.constants.rfc1036">
230
+
<varlistentry xml:id="datetimeinterface.constants.rfc1036">
181
231
<term><constant>DateTimeInterface::RFC1036</constant></term>
182
232
<term><constant>DATE_RFC1036</constant></term>
183
233
<listitem>
...
...
@@ -187,7 +237,7 @@
187
237
</listitem>
188
238
</varlistentry>
189
239

190
-
<varlistentry xml:id="datetime.constants.rfc1123">
240
+
<varlistentry xml:id="datetimeinterface.constants.rfc1123">
191
241
<term><constant>DateTimeInterface::RFC1123</constant></term>
192
242
<term><constant>DATE_RFC1123</constant></term>
193
243
<listitem>
...
...
@@ -197,7 +247,17 @@
197
247
</listitem>
198
248
</varlistentry>
199
249

200
-
<varlistentry xml:id="datetime.constants.rfc2822">
250
+
<varlistentry xml:id="datetimeinterface.constants.rfc7231">
251
+
<term><constant>DateTimeInterface::RFC7231</constant></term>
252
+
<term><constant>DATE_RFC7231</constant></term>
253
+
<listitem>
254
+
<simpara>
255
+
RFC 7231 (since PHP 7.0.19 and 7.1.5) (example: Sat, 30 Apr 2016 17:52:13 GMT)
256
+
</simpara>
257
+
</listitem>
258
+
</varlistentry>
259
+

260
+
<varlistentry xml:id="datetimeinterface.constants.rfc2822">
201
261
<term><constant>DateTimeInterface::RFC2822</constant></term>
202
262
<term><constant>DATE_RFC2822</constant></term>
203
263
<listitem>
...
...
@@ -207,27 +267,27 @@
207
267
</listitem>
208
268
</varlistentry>
209
269

210
-
<varlistentry xml:id="datetime.constants.rfc3339">
270
+
<varlistentry xml:id="datetimeinterface.constants.rfc3339">
211
271
<term><constant>DateTimeInterface::RFC3339</constant></term>
212
272
<term><constant>DATE_RFC3339</constant></term>
213
273
<listitem>
214
274
<simpara>
215
-
Same as <constant>DATE_ATOM</constant> (since PHP 5.1.3)
275
+
Same as <constant>DATE_ATOM</constant>
216
276
</simpara>
217
277
</listitem>
218
278
</varlistentry>
219
279

220
-
<varlistentry xml:id="datetime.constants.rfc3339_extended">
280
+
<varlistentry xml:id="datetimeinterface.constants.rfc3339-extended">
221
281
<term><constant>DateTimeInterface::RFC3339_EXTENDED</constant></term>
222
282
<term><constant>DATE_RFC3339_EXTENDED</constant></term>
223
283
<listitem>
224
284
<simpara>
225
-
RFC 3339 EXTENDED format (since PHP 7.0.0) (example: 2005-08-15T15:52:01.000+00:00)
285
+
RFC 3339 EXTENDED format (example: 2005-08-15T15:52:01.000+00:00)
226
286
</simpara>
227
287
</listitem>
228
288
</varlistentry>
229
289

230
-
<varlistentry xml:id="datetime.constants.rss">
290
+
<varlistentry xml:id="datetimeinterface.constants.rss">
231
291
<term><constant>DateTimeInterface::RSS</constant></term>
232
292
<term><constant>DATE_RSS</constant></term>
233
293
<listitem>
...
...
@@ -237,7 +297,7 @@
237
297
</listitem>
238
298
</varlistentry>
239
299

240
-
<varlistentry xml:id="datetime.constants.w3c">
300
+
<varlistentry xml:id="datetimeinterface.constants.w3c">
241
301
<term><constant>DateTimeInterface::W3C</constant></term>
242
302
<term><constant>DATE_W3C</constant></term>
243
303
<listitem>
...
...
@@ -264,18 +324,17 @@
264
324
</thead>
265
325
<tbody>
266
326
<row>
267
-
<entry>7.2.0</entry>
327
+
<entry>8.2.0</entry>
268
328
<entry>
269
-
The class constants of <classname>DateTime</classname> are now defined
270
-
on <classname>DateTimeInterface</classname>.
329
+
The constant <constant linkend="datetimeinterface.constants.iso8601-expanded">DateTimeInterface::ISO8601_EXPANDED</constant>
330
+
was added.
271
331
</entry>
272
332
</row>
273
333
<row>
274
-
<entry>5.5.8</entry>
334
+
<entry>7.2.0</entry>
275
335
<entry>
276
-
Trying to implement <classname>DateTimeInterface</classname> raises a
277
-
fatal error now. Formerly implementing the interface didn't raise an
278
-
error, but the behavior was erroneous.
336
+
The class constants of <classname>DateTime</classname> are now defined
337
+
on <interfacename>DateTimeInterface</interfacename>.
279
338
</entry>
280
339
</row>
281
340
</tbody>
...
...
@@ -289,7 +348,6 @@
289
348
&reference.datetime.entities.datetimeinterface;
290
349

291
350
</phpdoc:classref>
292
-

293
351
<!-- Keep this comment at the end of the file
294
352
Local variables:
295
353
mode: sgml
296
354