reference/datetime/datetimeinterface/diff.xml
52222422c00aba192c5f7fed3c4efdaa870e799e
52222422c00aba192c5f7fed3c4efdaa870e799e
...
...
@@ -22,13 +22,13 @@
22
22
<methodparam><type>DateTimeInterface</type><parameter>targetObject</parameter></methodparam>
23
23
<methodparam choice="opt"><type>bool</type><parameter>absolute</parameter><initializer>&false;</initializer></methodparam>
24
24
</methodsynopsis>
25
-
<methodsynopsis role="oop">
25
+
<methodsynopsis role="DateTime">
26
26
<modifier>public</modifier> <type>DateInterval</type><methodname>DateTime::diff</methodname>
27
27
<methodparam><type>DateTimeInterface</type><parameter>targetObject</parameter></methodparam>
28
28
<methodparam choice="opt"><type>bool</type><parameter>absolute</parameter><initializer>&false;</initializer></methodparam>
29
29
</methodsynopsis>
30
30
<para>&style.procedural;</para>
31
-
<methodsynopsis role="procedural">
31
+
<methodsynopsis>
32
32
<type>DateInterval</type><methodname>date_diff</methodname>
33
33
<methodparam><type>DateTimeInterface</type><parameter>baseObject</parameter></methodparam>
34
34
<methodparam><type>DateTimeInterface</type><parameter>targetObject</parameter></methodparam>
...
...
@@ -69,12 +69,24 @@
69
69
difference between the two dates.
70
70
</para>
71
71
<para>
72
-
The return value more specifically represents the interval to apply to the
73
-
original object (<parameter>$this</parameter> or
72
+
The <parameter>absolute</parameter> parameter only affects the
73
+
<parameter>invert</parameter> property of a
74
+
<classname>DateInterval</classname> object.
75
+
</para>
76
+
<para>
77
+
The return value more specifically represents the clock-time interval to
78
+
apply to the original object (<parameter>$this</parameter> or
74
79
<parameter>$originObject</parameter>) to arrive at the
75
80
<parameter>$targetObject</parameter>. This process is not always
76
81
reversible.
77
82
</para>
83
+
<para>
84
+
The method is aware of DST changeovers, and hence can return an interval of
85
+
<literal>24 hours and 30 minutes</literal>, as per one of the examples. If
86
+
you want to calculate with absolute time, you need to convert both the
87
+
<parameter>$this</parameter>/<parameter>$baseObject</parameter>, and
88
+
<parameter>$targetObject</parameter> to UTC first.
89
+
</para>
78
90
</refsect1>
79
91
80
92
<refsect1 role="examples">
...
...
@@ -110,6 +122,54 @@ echo $interval->format('%R%a days');
110
122
]]>
111
123
</screen>
112
124
</example>
125
+
126
+
<example>
127
+
<title><methodname>DateTimeInterface::diff</methodname> during DST
128
+
changeover</title>
129
+
<programlisting role="php">
130
+
<![CDATA[
131
+
<?php
132
+
$originalTime = new DateTimeImmutable("2021-10-30 09:00:00 Europe/London");
133
+
$targetTime = new DateTimeImmutable("2021-10-31 08:30:00 Europe/London");
134
+
$interval = $originalTime->diff($targetTime);
135
+
echo $interval->format("%H:%I:%S (Full days: %a)"), "\n";
136
+
?>
137
+
]]>
138
+
</programlisting>
139
+
&example.outputs;
140
+
<screen>
141
+
<![CDATA[
142
+
24:30:00 (Full days: 0)
143
+
]]>
144
+
</screen>
145
+
</example>
146
+
147
+
<example>
148
+
<title><methodname>DateTimeInterface::diff</methodname> range</title>
149
+
<para>
150
+
The value that the method returns is the exact amount of time to get from
151
+
<parameter>$this</parameter> to <parameter>$targetObject</parameter>.
152
+
Comparing January 1st to December 31st returns therefore 364, and not 365,
153
+
days (for non-leap years).
154
+
</para>
155
+
<programlisting role="php">
156
+
<![CDATA[
157
+
<?php
158
+
$originalTime = new DateTimeImmutable("2023-01-01 UTC");
159
+
$targetTime = new DateTimeImmutable("2023-12-31 UTC");
160
+
$interval = $originalTime->diff($targetTime);
161
+
echo "Full days: ", $interval->format("%a"), "\n";
162
+
?>
163
+
]]>
164
+
</programlisting>
165
+
&example.outputs;
166
+
<screen>
167
+
<![CDATA[
168
+
Full days: 364
169
+
]]>
170
+
</screen>
171
+
</example>
172
+
113
173
<example>
114
174
<title><classname>DateTime</classname> object comparison</title>
115
175
<note>
116
176