reference/datetime/datetimeinterface/diff.xml
dbbcd32d72e4c9af14e9f3b940edbedfb54f965e
...
...
@@ -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,19 @@
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 return value more specifically represents the clock-time interval to
73
+
apply to the original object (<parameter>$this</parameter> or
74
74
<parameter>$originObject</parameter>) to arrive at the
75
75
<parameter>$targetObject</parameter>. This process is not always
76
76
reversible.
77
77
</para>
78
+
<para>
79
+
The method is aware of DST changeovers, and hence can return an interval of
80
+
<literal>24 hours and 30 minutes</literal>, as per one of the examples. If
81
+
you want to calculate with absolute time, you need to convert both the
82
+
<parameter>$this</parameter>/<parameter>$baseObject</parameter>, and
83
+
<parameter>$targetObject</parameter> to UTC first.
84
+
</para>
78
85
</refsect1>
79
86

80
87
<refsect1 role="examples">
...
...
@@ -110,6 +117,54 @@ echo $interval->format('%R%a days');
110
117
]]>
111
118
</screen>
112
119
</example>
120
+

121
+
<example>
122
+
<title><methodname>DateTimeInterface::diff</methodname> during DST
123
+
changeover</title>
124
+
<programlisting role="php">
125
+
<![CDATA[
126
+
<?php
127
+
$originalTime = new DateTimeImmutable("2021-10-30 09:00:00 Europe/London");
128
+
$targedTime = new DateTimeImmutable("2021-10-31 08:30:00 Europe/London");
129
+
$interval = $originalTime->diff($targedTime);
130
+
echo $interval->format("%H:%I:%S (Full days: %a)"), "\n";
131
+
?>
132
+
]]>
133
+
</programlisting>
134
+
&example.outputs;
135
+
<screen>
136
+
<![CDATA[
137
+
24:30:00 (Full days: 0)
138
+
]]>
139
+
</screen>
140
+
</example>
141
+

142
+
<example>
143
+
<title><methodname>DateTimeInterface::diff</methodname> range</title>
144
+
<para>
145
+
The value that the method returns is the exact amount of time to get from
146
+
<parameter>$this</parameter> to <parameter>$targetObject</parameter>.
147
+
Comparing January 1st to December 31st returns therefore 364, and not 365,
148
+
days (for non-leap years).
149
+
</para>
150
+
<programlisting role="php">
151
+
<![CDATA[
152
+
<?php
153
+
$originalTime = new DateTimeImmutable("2023-01-01 UTC");
154
+
$targedTime = new DateTimeImmutable("2023-12-31 UTC");
155
+
$interval = $originalTime->diff($targedTime);
156
+
echo "Full days: ", $interval->format("%a"), "\n";
157
+
?>
158
+
]]>
159
+
</programlisting>
160
+
&example.outputs;
161
+
<screen>
162
+
<![CDATA[
163
+
Full days: 364
164
+
]]>
165
+
</screen>
166
+
</example>
167
+

113
168
<example>
114
169
<title><classname>DateTime</classname> object comparison</title>
115
170
<note>
116
171