reference/datetime/dateinterval.xml
9154789dfc9cb8aa5df644bfba5e86c2deba4cb8
9154789dfc9cb8aa5df644bfba5e86c2deba4cb8
...
...
@@ -1,6 +1,5 @@
1
1
<?xml version="1.0" encoding="utf-8"?>
2
2
<!-- $Revision$ -->
3
-
4
3
<phpdoc:classref xml:id="class.dateinterval" 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 DateInterval class</title>
...
...
@@ -17,7 +16,23 @@
17
16
<para>
18
17
A date interval stores either a fixed amount of time (in years, months,
19
18
days, hours etc) or a relative time string in the format that
20
-
<classname>DateTime</classname>'s constructor supports.
19
+
<classname>DateTimeImmutable</classname>'s and
20
+
<classname>DateTime</classname>'s constructors support.
21
+
</para>
22
+
<para>
23
+
More specifically, the information in an object of the
24
+
<classname>DateInterval</classname> class is an instruction to get from
25
+
one date/time to another date/time. This process is not always reversible.
26
+
</para>
27
+
<para>
28
+
A common way to create a <classname>DateInterval</classname> object
29
+
is by calculating the difference between two date/time objects through
30
+
<methodname>DateTimeInterface::diff</methodname>.
31
+
</para>
32
+
<para>
33
+
Since there is no well defined way to compare date intervals,
34
+
<classname>DateInterval</classname> instances are
35
+
<link linkend="language.operators.comparison.incomparable">incomparable</link>.
21
36
</para>
22
37
</section>
23
38
<!-- }}} -->
...
...
@@ -26,46 +41,40 @@
26
41
&reftitle.classsynopsis;
27
42
28
43
<!-- {{{ Synopsis -->
29
-
<classsynopsis>
30
-
<ooclass><classname>DateInterval</classname></ooclass>
31
-
32
-
<!-- {{{ Class synopsis -->
33
-
<classsynopsisinfo>
34
-
<ooclass>
35
-
<classname>DateInterval</classname>
36
-
</ooclass>
37
-
</classsynopsisinfo>
38
-
<!-- }}} -->
44
+
<classsynopsis class="class">
45
+
<ooclass>
46
+
<classname>DateInterval</classname>
47
+
</ooclass>
39
48
40
49
<classsynopsisinfo role="comment">&Properties;</classsynopsisinfo>
41
50
<fieldsynopsis>
42
51
<modifier>public</modifier>
43
-
<type>integer</type>
52
+
<type>int</type>
44
53
<varname linkend="dateinterval.props.y">y</varname>
45
54
</fieldsynopsis>
46
55
<fieldsynopsis>
47
56
<modifier>public</modifier>
48
-
<type>integer</type>
57
+
<type>int</type>
49
58
<varname linkend="dateinterval.props.m">m</varname>
50
59
</fieldsynopsis>
51
60
<fieldsynopsis>
52
61
<modifier>public</modifier>
53
-
<type>integer</type>
62
+
<type>int</type>
54
63
<varname linkend="dateinterval.props.d">d</varname>
55
64
</fieldsynopsis>
56
65
<fieldsynopsis>
57
66
<modifier>public</modifier>
58
-
<type>integer</type>
67
+
<type>int</type>
59
68
<varname linkend="dateinterval.props.h">h</varname>
60
69
</fieldsynopsis>
61
70
<fieldsynopsis>
62
71
<modifier>public</modifier>
63
-
<type>integer</type>
72
+
<type>int</type>
64
73
<varname linkend="dateinterval.props.i">i</varname>
65
74
</fieldsynopsis>
66
75
<fieldsynopsis>
67
76
<modifier>public</modifier>
68
-
<type>integer</type>
77
+
<type>int</type>
69
78
<varname linkend="dateinterval.props.s">s</varname>
70
79
</fieldsynopsis>
71
80
<fieldsynopsis>
...
...
@@ -75,7 +84,7 @@
75
84
</fieldsynopsis>
76
85
<fieldsynopsis>
77
86
<modifier>public</modifier>
78
-
<type>integer</type>
87
+
<type>int</type>
79
88
<varname linkend="dateinterval.props.invert">invert</varname>
80
89
</fieldsynopsis>
81
90
<fieldsynopsis>
...
...
@@ -83,20 +92,24 @@
83
92
<type>mixed</type>
84
93
<varname linkend="dateinterval.props.days">days</varname>
85
94
</fieldsynopsis>
95
+
<fieldsynopsis>
96
+
<modifier>public</modifier>
97
+
<type>bool</type>
98
+
<varname linkend="dateinterval.props.from-string">from_string</varname>
99
+
</fieldsynopsis>
100
+
<fieldsynopsis>
101
+
<modifier>public</modifier>
102
+
<type>string</type>
103
+
<varname linkend="dateinterval.props.date-string">date_string</varname>
104
+
</fieldsynopsis>
86
105
87
106
<classsynopsisinfo role="comment">&Methods;</classsynopsisinfo>
88
-
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.dateinterval')/db:refentry/db:refsect1[@role='description']/descendant::db:constructorsynopsis[not(@role='procedural')])">
89
-
<xi:fallback />
107
+
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.dateinterval')/db:refentry/db:refsect1[@role='description']/descendant::db:constructorsynopsis[@role='DateInterval'])">
108
+
<xi:fallback/>
90
109
</xi:include>
91
-
<!--
92
-
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.dateinterval')/db:refentry/db:refsect1[@role='description']/descendant::db:destructorsynopsis[not(@role='procedural')])">
93
-
<xi:fallback />
110
+
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.dateinterval')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[@role='DateInterval'])">
111
+
<xi:fallback/>
94
112
</xi:include>
95
-
-->
96
-
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.dateinterval')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[not(@role='procedural')])">
97
-
<xi:fallback />
98
-
</xi:include>
99
-
100
113
</classsynopsis>
101
114
<!-- }}} -->
102
115
...
...
@@ -104,6 +117,12 @@
104
117
105
118
<section xml:id="dateinterval.props">
106
119
&reftitle.properties;
120
+
<warning>
121
+
<para>
122
+
The available properties listed below depend on PHP version, and should
123
+
be considered as <emphasis>readonly</emphasis>.
124
+
</para>
125
+
</warning>
107
126
<variablelist>
108
127
<varlistentry xml:id="dateinterval.props.y">
109
128
<term><varname>y</varname></term>
...
...
@@ -177,13 +196,33 @@
177
196
<listitem>
178
197
<para>
179
198
If the DateInterval object was created by
180
-
<function>DateTime::diff</function>, then this is the total number of
181
-
days between the start and end dates. Otherwise,
199
+
<methodname>DateTimeImmutable::diff</methodname> or
200
+
<methodname>DateTime::diff</methodname>, then this is the
201
+
total number of full days between the start and end dates. Otherwise,
182
202
<varname>days</varname> will be &false;.
183
203
</para>
204
+
</listitem>
205
+
</varlistentry>
206
+
<varlistentry xml:id="dateinterval.props.from-string">
207
+
<term><varname>from_string</varname></term>
208
+
<listitem>
209
+
<para>
210
+
If the DateInterval object was created by
211
+
<methodname>DateInterval::createFromDateString</methodname>, then
212
+
this property's value will be &true;, and the
213
+
<varname>date_string</varname> property will be populated. Otherwise,
214
+
the value will be &false;, and the <varname>y</varname> to
215
+
<varname>f</varname>, <varname>invert</varname>, and
216
+
<varname>days</varname> properties will be populated.
217
+
</para>
218
+
</listitem>
219
+
</varlistentry>
220
+
<varlistentry xml:id="dateinterval.props.date-string">
221
+
<term><varname>date_string</varname></term>
222
+
<listitem>
184
223
<para>
185
-
Before PHP 5.4.20/5.5.4 instead of &false; you will receive -99999 upon
186
-
accessing the property.
224
+
The string used as argument to
225
+
<methodname>DateInterval::createFromDateString</methodname>.
187
226
</para>
188
227
</listitem>
189
228
</varlistentry>
...
...
@@ -203,6 +242,29 @@
203
242
</thead>
204
243
<tbody>
205
244
<row>
245
+
<entry>8.2.0</entry>
246
+
<entry>
247
+
The <varname>from_string</varname> and <varname>date_string</varname>
248
+
properties were added for <classname>DateInterval</classname>
249
+
instances that were created using the
250
+
<methodname>DateInterval::createFromDateString</methodname> method.
251
+
</entry>
252
+
</row>
253
+
<row>
254
+
<entry>8.2.0</entry>
255
+
<entry>
256
+
Only the <literal>y</literal> to <literal>f</literal>,
257
+
<literal>invert</literal>, and <literal>days</literal> will be visible.
258
+
</entry>
259
+
</row>
260
+
<row>
261
+
<entry>7.4.0</entry>
262
+
<entry>
263
+
<classname>DateInterval</classname> instances are incomparable now;
264
+
previously, all <classname>DateInterval</classname> instances were considered equal.
265
+
</entry>
266
+
</row>
267
+
<row>
206
268
<entry>7.1.0</entry>
207
269
<entry>The <varname>f</varname> property was added.</entry>
208
270
</row>
...
...
@@ -217,7 +279,6 @@
217
279
&reference.datetime.entities.dateinterval;
218
280
219
281
</phpdoc:classref>
220
-
221
282
<!-- Keep this comment at the end of the file
222
283
Local variables:
223
284
mode: sgml
224
285