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,9 +11,19 @@
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
<!-- }}} -->
...
...
@@ -23,109 +32,125 @@
23
32
&reftitle.interfacesynopsis;
24
33

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

29
-
<!-- {{{ Class synopsis -->
30
-
<classsynopsisinfo>
31
-
<oointerface>
32
-
<interfacename>DateTimeInterface</interfacename>
33
-
</oointerface>
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>
51
57
<modifier>const</modifier>
52
58
<type>string</type>
53
-
<varname linkend="datetime.constants.iso8601">DateTimeInterface::ISO8601</varname>
54
-
<initializer>"Y-m-d\TH:i:sO"</initializer>
59
+
<varname linkend="datetimeinterface.constants.iso8601">DateTimeInterface::ISO8601</varname>
60
+
<initializer>"Y-m-d\\TH:i:sO"</initializer>
55
61
</fieldsynopsis>
56
62
<fieldsynopsis>
63
+
<modifier>public</modifier>
57
64
<modifier>const</modifier>
58
65
<type>string</type>
59
-
<varname linkend="datetime.constants.rfc822">DateTimeInterface::RFC822</varname>
66
+
<varname linkend="datetimeinterface.constants.iso8601-expanded">DateTimeInterface::ISO8601_EXPANDED</varname>
67
+
<initializer>"X-m-d\\TH:i:sP"</initializer>
68
+
</fieldsynopsis>
69
+
<fieldsynopsis>
70
+
<modifier>public</modifier>
71
+
<modifier>const</modifier>
72
+
<type>string</type>
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>
81
-
<modifier>const</modifier>
82
-
<type>string</type>
83
-
<varname linkend="datetime.constants.rfc7231">DateTimeInterface::RFC7231</varname>
84
-
<initializer>"D, d M Y H:i:s \G\M\T"</initializer>
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>
85
103
</fieldsynopsis>
86
104
<fieldsynopsis>
105
+
<modifier>public</modifier>
87
106
<modifier>const</modifier>
88
107
<type>string</type>
89
-
<varname linkend="datetime.constants.rfc2822">DateTimeInterface::RFC2822</varname>
108
+
<varname linkend="datetimeinterface.constants.rfc2822">DateTimeInterface::RFC2822</varname>
90
109
<initializer>"D, d M Y H:i:s O"</initializer>
91
110
</fieldsynopsis>
92
111
<fieldsynopsis>
112
+
<modifier>public</modifier>
93
113
<modifier>const</modifier>
94
114
<type>string</type>
95
-
<varname linkend="datetime.constants.rfc3339">DateTimeInterface::RFC3339</varname>
96
-
<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>
97
117
</fieldsynopsis>
98
118
<fieldsynopsis>
119
+
<modifier>public</modifier>
99
120
<modifier>const</modifier>
100
121
<type>string</type>
101
-
<varname linkend="datetime.constants.rfc3339_extended">DateTimeInterface::RFC3339_EXTENDED</varname>
102
-
<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>
103
124
</fieldsynopsis>
104
125
<fieldsynopsis>
126
+
<modifier>public</modifier>
105
127
<modifier>const</modifier>
106
128
<type>string</type>
107
-
<varname linkend="datetime.constants.rss">DateTimeInterface::RSS</varname>
129
+
<varname linkend="datetimeinterface.constants.rss">DateTimeInterface::RSS</varname>
108
130
<initializer>"D, d M Y H:i:s O"</initializer>
109
131
</fieldsynopsis>
110
132
<fieldsynopsis>
133
+
<modifier>public</modifier>
111
134
<modifier>const</modifier>
112
135
<type>string</type>
113
-
<varname linkend="datetime.constants.w3c">DateTimeInterface::W3C</varname>
114
-
<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>
115
138
</fieldsynopsis>
116
139

117
140
<classsynopsisinfo role="comment">&Methods;</classsynopsisinfo>
118
-
<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>
119
144
</classsynopsis>
120
145
<!-- }}} -->
121
146

122
147
</section>
123
148

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

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

148
-
<varlistentry xml:id="datetime.constants.iso8601">
173
+
<varlistentry xml:id="datetimeinterface.constants.iso8601">
149
174
<term><constant>DateTimeInterface::ISO8601</constant></term>
150
175
<term><constant>DATE_ISO8601</constant></term>
151
176
<listitem>
...
...
@@ -155,15 +180,34 @@
155
180
<note>
156
181
<simpara>
157
182
This format is not compatible with ISO-8601, but is left this way for
158
-
backward compatibility reasons. Use <constant>DateTime::ATOM</constant>
159
-
or <constant>DATE_ATOM</constant> for compatibility with ISO-8601
160
-
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.
161
205
</simpara>
162
206
</note>
163
207
</listitem>
164
208
</varlistentry>
165
209

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

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

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

196
-
<varlistentry xml:id="datetime.constants.rfc1123">
240
+
<varlistentry xml:id="datetimeinterface.constants.rfc1123">
197
241
<term><constant>DateTimeInterface::RFC1123</constant></term>
198
242
<term><constant>DATE_RFC1123</constant></term>
199
243
<listitem>
...
...
@@ -203,7 +247,7 @@
203
247
</listitem>
204
248
</varlistentry>
205
249

206
-
<varlistentry xml:id="datetime.constants.rfc7231">
250
+
<varlistentry xml:id="datetimeinterface.constants.rfc7231">
207
251
<term><constant>DateTimeInterface::RFC7231</constant></term>
208
252
<term><constant>DATE_RFC7231</constant></term>
209
253
<listitem>
...
...
@@ -213,7 +257,7 @@
213
257
</listitem>
214
258
</varlistentry>
215
259

216
-
<varlistentry xml:id="datetime.constants.rfc2822">
260
+
<varlistentry xml:id="datetimeinterface.constants.rfc2822">
217
261
<term><constant>DateTimeInterface::RFC2822</constant></term>
218
262
<term><constant>DATE_RFC2822</constant></term>
219
263
<listitem>
...
...
@@ -223,7 +267,7 @@
223
267
</listitem>
224
268
</varlistentry>
225
269

226
-
<varlistentry xml:id="datetime.constants.rfc3339">
270
+
<varlistentry xml:id="datetimeinterface.constants.rfc3339">
227
271
<term><constant>DateTimeInterface::RFC3339</constant></term>
228
272
<term><constant>DATE_RFC3339</constant></term>
229
273
<listitem>
...
...
@@ -233,7 +277,7 @@
233
277
</listitem>
234
278
</varlistentry>
235
279

236
-
<varlistentry xml:id="datetime.constants.rfc3339_extended">
280
+
<varlistentry xml:id="datetimeinterface.constants.rfc3339-extended">
237
281
<term><constant>DateTimeInterface::RFC3339_EXTENDED</constant></term>
238
282
<term><constant>DATE_RFC3339_EXTENDED</constant></term>
239
283
<listitem>
...
...
@@ -243,7 +287,7 @@
243
287
</listitem>
244
288
</varlistentry>
245
289

246
-
<varlistentry xml:id="datetime.constants.rss">
290
+
<varlistentry xml:id="datetimeinterface.constants.rss">
247
291
<term><constant>DateTimeInterface::RSS</constant></term>
248
292
<term><constant>DATE_RSS</constant></term>
249
293
<listitem>
...
...
@@ -253,7 +297,7 @@
253
297
</listitem>
254
298
</varlistentry>
255
299

256
-
<varlistentry xml:id="datetime.constants.w3c">
300
+
<varlistentry xml:id="datetimeinterface.constants.w3c">
257
301
<term><constant>DateTimeInterface::W3C</constant></term>
258
302
<term><constant>DATE_W3C</constant></term>
259
303
<listitem>
...
...
@@ -280,10 +324,17 @@
280
324
</thead>
281
325
<tbody>
282
326
<row>
327
+
<entry>8.2.0</entry>
328
+
<entry>
329
+
The constant <constant linkend="datetimeinterface.constants.iso8601-expanded">DateTimeInterface::ISO8601_EXPANDED</constant>
330
+
was added.
331
+
</entry>
332
+
</row>
333
+
<row>
283
334
<entry>7.2.0</entry>
284
335
<entry>
285
336
The class constants of <classname>DateTime</classname> are now defined
286
-
on <classname>DateTimeInterface</classname>.
337
+
on <interfacename>DateTimeInterface</interfacename>.
287
338
</entry>
288
339
</row>
289
340
</tbody>
...
...
@@ -297,7 +348,6 @@
297
348
&reference.datetime.entities.datetimeinterface;
298
349

299
350
</phpdoc:classref>
300
-

301
351
<!-- Keep this comment at the end of the file
302
352
Local variables:
303
353
mode: sgml
304
354