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

4
-
<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">
3
+
<reference xml:id="class.datetimeinterface" role="class" 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>
7
6
<titleabbrev>DateTimeInterface</titleabbrev>
...
...
@@ -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,110 +32,129 @@
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">
129
-
<term><constant>DateTimeInterface::ATOM</constant></term>
153
+
<varlistentry xml:id="datetimeinterface.constants.atom">
154
+
<term>
155
+
<constant>DateTimeInterface::ATOM</constant>
156
+
<type>string</type>
157
+
</term>
130
158
<term><constant>DATE_ATOM</constant></term>
131
159
<listitem>
132
160
<simpara>
...
...
@@ -135,8 +163,11 @@
135
163
</listitem>
136
164
</varlistentry>
137
165

138
-
<varlistentry xml:id="datetime.constants.cookie">
139
-
<term><constant>DateTimeInterface::COOKIE</constant></term>
166
+
<varlistentry xml:id="datetimeinterface.constants.cookie">
167
+
<term>
168
+
<constant>DateTimeInterface::COOKIE</constant>
169
+
<type>string</type>
170
+
</term>
140
171
<term><constant>DATE_COOKIE</constant></term>
141
172
<listitem>
142
173
<simpara>
...
...
@@ -145,8 +176,11 @@
145
176
</listitem>
146
177
</varlistentry>
147
178

148
-
<varlistentry xml:id="datetime.constants.iso8601">
149
-
<term><constant>DateTimeInterface::ISO8601</constant></term>
179
+
<varlistentry xml:id="datetimeinterface.constants.iso8601">
180
+
<term>
181
+
<constant>DateTimeInterface::ISO8601</constant>
182
+
<type>string</type>
183
+
</term>
150
184
<term><constant>DATE_ISO8601</constant></term>
151
185
<listitem>
152
186
<simpara>
...
...
@@ -155,16 +189,41 @@
155
189
<note>
156
190
<simpara>
157
191
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.
192
+
backward compatibility reasons. Use
193
+
<constant>DateTimeInterface::ISO8601_EXPANDED</constant>,
194
+
<constant>DateTimeInterface::ATOM</constant> for compatibility with ISO-8601
195
+
instead. (ref ISO8601:2004 section 4.3.3 clause d)
196
+
</simpara>
197
+
</note>
198
+
</listitem>
199
+
</varlistentry>
200
+

201
+
<varlistentry xml:id="datetimeinterface.constants.iso8601-expanded">
202
+
<term>
203
+
<constant>DateTimeInterface::ISO8601_EXPANDED</constant>
204
+
<type>string</type>
205
+
</term>
206
+
<term><constant>DATE_ISO8601_EXPANDED</constant></term>
207
+
<listitem>
208
+
<simpara>
209
+
ISO-8601 Expanded (example: +10191-07-26T08:59:52+01:00)
210
+
</simpara>
211
+
<note>
212
+
<simpara>
213
+
This format allows for year ranges outside of ISO-8601's normal range
214
+
of <literal>0000</literal>-<literal>9999</literal> by always
215
+
including a sign character. It also ensures that the timezone part
216
+
(<literal>+01:00</literal>) is compatible with ISO-8601.
161
217
</simpara>
162
218
</note>
163
219
</listitem>
164
220
</varlistentry>
165
221

166
-
<varlistentry xml:id="datetime.constants.rfc822">
167
-
<term><constant>DateTimeInterface::RFC822</constant></term>
222
+
<varlistentry xml:id="datetimeinterface.constants.rfc822">
223
+
<term>
224
+
<constant>DateTimeInterface::RFC822</constant>
225
+
<type>string</type>
226
+
</term>
168
227
<term><constant>DATE_RFC822</constant></term>
169
228
<listitem>
170
229
<simpara>
...
...
@@ -173,8 +232,11 @@
173
232
</listitem>
174
233
</varlistentry>
175
234

176
-
<varlistentry xml:id="datetime.constants.rfc850">
177
-
<term><constant>DateTimeInterface::RFC850</constant></term>
235
+
<varlistentry xml:id="datetimeinterface.constants.rfc850">
236
+
<term>
237
+
<constant>DateTimeInterface::RFC850</constant>
238
+
<type>string</type>
239
+
</term>
178
240
<term><constant>DATE_RFC850</constant></term>
179
241
<listitem>
180
242
<simpara>
...
...
@@ -183,8 +245,11 @@
183
245
</listitem>
184
246
</varlistentry>
185
247

186
-
<varlistentry xml:id="datetime.constants.rfc1036">
187
-
<term><constant>DateTimeInterface::RFC1036</constant></term>
248
+
<varlistentry xml:id="datetimeinterface.constants.rfc1036">
249
+
<term>
250
+
<constant>DateTimeInterface::RFC1036</constant>
251
+
<type>string</type>
252
+
</term>
188
253
<term><constant>DATE_RFC1036</constant></term>
189
254
<listitem>
190
255
<simpara>
...
...
@@ -193,8 +258,11 @@
193
258
</listitem>
194
259
</varlistentry>
195
260

196
-
<varlistentry xml:id="datetime.constants.rfc1123">
197
-
<term><constant>DateTimeInterface::RFC1123</constant></term>
261
+
<varlistentry xml:id="datetimeinterface.constants.rfc1123">
262
+
<term>
263
+
<constant>DateTimeInterface::RFC1123</constant>
264
+
<type>string</type>
265
+
</term>
198
266
<term><constant>DATE_RFC1123</constant></term>
199
267
<listitem>
200
268
<simpara>
...
...
@@ -203,8 +271,11 @@
203
271
</listitem>
204
272
</varlistentry>
205
273

206
-
<varlistentry xml:id="datetime.constants.rfc7231">
207
-
<term><constant>DateTimeInterface::RFC7231</constant></term>
274
+
<varlistentry xml:id="datetimeinterface.constants.rfc7231">
275
+
<term>
276
+
<constant>DateTimeInterface::RFC7231</constant>
277
+
<type>string</type>
278
+
</term>
208
279
<term><constant>DATE_RFC7231</constant></term>
209
280
<listitem>
210
281
<simpara>
...
...
@@ -213,8 +284,11 @@
213
284
</listitem>
214
285
</varlistentry>
215
286

216
-
<varlistentry xml:id="datetime.constants.rfc2822">
217
-
<term><constant>DateTimeInterface::RFC2822</constant></term>
287
+
<varlistentry xml:id="datetimeinterface.constants.rfc2822">
288
+
<term>
289
+
<constant>DateTimeInterface::RFC2822</constant>
290
+
<type>string</type>
291
+
</term>
218
292
<term><constant>DATE_RFC2822</constant></term>
219
293
<listitem>
220
294
<simpara>
...
...
@@ -223,8 +297,11 @@
223
297
</listitem>
224
298
</varlistentry>
225
299

226
-
<varlistentry xml:id="datetime.constants.rfc3339">
227
-
<term><constant>DateTimeInterface::RFC3339</constant></term>
300
+
<varlistentry xml:id="datetimeinterface.constants.rfc3339">
301
+
<term>
302
+
<constant>DateTimeInterface::RFC3339</constant>
303
+
<type>string</type>
304
+
</term>
228
305
<term><constant>DATE_RFC3339</constant></term>
229
306
<listitem>
230
307
<simpara>
...
...
@@ -233,8 +310,11 @@
233
310
</listitem>
234
311
</varlistentry>
235
312

236
-
<varlistentry xml:id="datetime.constants.rfc3339_extended">
237
-
<term><constant>DateTimeInterface::RFC3339_EXTENDED</constant></term>
313
+
<varlistentry xml:id="datetimeinterface.constants.rfc3339-extended">
314
+
<term>
315
+
<constant>DateTimeInterface::RFC3339_EXTENDED</constant>
316
+
<type>string</type>
317
+
</term>
238
318
<term><constant>DATE_RFC3339_EXTENDED</constant></term>
239
319
<listitem>
240
320
<simpara>
...
...
@@ -243,8 +323,11 @@
243
323
</listitem>
244
324
</varlistentry>
245
325

246
-
<varlistentry xml:id="datetime.constants.rss">
247
-
<term><constant>DateTimeInterface::RSS</constant></term>
326
+
<varlistentry xml:id="datetimeinterface.constants.rss">
327
+
<term>
328
+
<constant>DateTimeInterface::RSS</constant>
329
+
<type>string</type>
330
+
</term>
248
331
<term><constant>DATE_RSS</constant></term>
249
332
<listitem>
250
333
<simpara>
...
...
@@ -253,8 +336,11 @@
253
336
</listitem>
254
337
</varlistentry>
255
338

256
-
<varlistentry xml:id="datetime.constants.w3c">
257
-
<term><constant>DateTimeInterface::W3C</constant></term>
339
+
<varlistentry xml:id="datetimeinterface.constants.w3c">
340
+
<term>
341
+
<constant>DateTimeInterface::W3C</constant>
342
+
<type>string</type>
343
+
</term>
258
344
<term><constant>DATE_W3C</constant></term>
259
345
<listitem>
260
346
<simpara>
...
...
@@ -267,37 +353,47 @@
267
353
</section>
268
354
<!-- }}} -->
269
355

270
-
<section role="changelog" xml:id="datetimeinterface.changelog"><!-- {{{ -->
271
-
&reftitle.changelog;
272
-
<para>
273
-
<informaltable>
274
-
<tgroup cols="2">
275
-
<thead>
276
-
<row>
277
-
<entry>&Version;</entry>
278
-
<entry>&Description;</entry>
279
-
</row>
280
-
</thead>
281
-
<tbody>
282
-
<row>
283
-
<entry>7.2.0</entry>
284
-
<entry>
285
-
The class constants of <classname>DateTime</classname> are now defined
286
-
on <classname>DateTimeInterface</classname>.
287
-
</entry>
288
-
</row>
289
-
</tbody>
290
-
</tgroup>
291
-
</informaltable>
292
-
</para>
293
-
</section><!-- }}} -->
356
+
<section role="changelog" xml:id="datetimeinterface.changelog"><!-- {{{ -->
357
+
&reftitle.changelog;
358
+
<para>
359
+
<informaltable>
360
+
<tgroup cols="2">
361
+
<thead>
362
+
<row>
363
+
<entry>&Version;</entry>
364
+
<entry>&Description;</entry>
365
+
</row>
366
+
</thead>
367
+
<tbody>
368
+
<row>
369
+
<entry>8.4.0</entry>
370
+
<entry>The class constants are now typed.</entry>
371
+
</row>
372
+
<row>
373
+
<entry>8.2.0</entry>
374
+
<entry>
375
+
The constant <constant linkend="datetimeinterface.constants.iso8601-expanded">DateTimeInterface::ISO8601_EXPANDED</constant>
376
+
was added.
377
+
</entry>
378
+
</row>
379
+
<row>
380
+
<entry>7.2.0</entry>
381
+
<entry>
382
+
The class constants of <classname>DateTime</classname> are now defined
383
+
on <interfacename>DateTimeInterface</interfacename>.
384
+
</entry>
385
+
</row>
386
+
</tbody>
387
+
</tgroup>
388
+
</informaltable>
389
+
</para>
390
+
</section><!-- }}} -->
294
391

295
392
</partintro>
296
393

297
394
&reference.datetime.entities.datetimeinterface;
298
395

299
-
</phpdoc:classref>
300
-

396
+
</reference>
301
397
<!-- Keep this comment at the end of the file
302
398
Local variables:
303
399
mode: sgml
304
400



Translation status