reference/datetime/datetimeinterface/diff.xml
dbbcd32d72e4c9af14e9f3b940edbedfb54f965e
...
...
@@ -1,11 +1,10 @@
1
1
<?xml version="1.0" encoding="utf-8"?>
2
2
<!-- $Revision$ -->
3
-

4
3
<refentry xml:id="datetime.diff" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
5
4
<refnamediv>
6
-
<refname>DateTime::diff</refname>
7
-
<refname>DateTimeImmutable::diff</refname>
8
5
<refname>DateTimeInterface::diff</refname>
6
+
<refname>DateTimeImmutable::diff</refname>
7
+
<refname>DateTime::diff</refname>
9
8
<refname>date_diff</refname>
10
9
<refpurpose>Returns the difference between two DateTime objects</refpurpose>
11
10
</refnamediv>
...
...
@@ -13,27 +12,27 @@
13
12
<refsect1 role="description">
14
13
&reftitle.description;
15
14
<para>&style.oop;</para>
16
-
<methodsynopsis role="oop">
17
-
<modifier>public</modifier> <type>DateInterval</type><methodname>DateTime::diff</methodname>
18
-
<methodparam><type>DateTimeInterface</type><parameter>datetime2</parameter></methodparam>
19
-
<methodparam choice="opt"><type>bool</type><parameter>absolute</parameter><initializer>false</initializer></methodparam>
15
+
<methodsynopsis role="DateTimeInterface">
16
+
<modifier>public</modifier> <type>DateInterval</type><methodname>DateTimeInterface::diff</methodname>
17
+
<methodparam><type>DateTimeInterface</type><parameter>targetObject</parameter></methodparam>
18
+
<methodparam choice="opt"><type>bool</type><parameter>absolute</parameter><initializer>&false;</initializer></methodparam>
20
19
</methodsynopsis>
21
20
<methodsynopsis role="DateTimeImmutable">
22
21
<modifier>public</modifier> <type>DateInterval</type><methodname>DateTimeImmutable::diff</methodname>
23
-
<methodparam><type>DateTimeInterface</type><parameter>datetime2</parameter></methodparam>
24
-
<methodparam choice="opt"><type>bool</type><parameter>absolute</parameter><initializer>false</initializer></methodparam>
22
+
<methodparam><type>DateTimeInterface</type><parameter>targetObject</parameter></methodparam>
23
+
<methodparam choice="opt"><type>bool</type><parameter>absolute</parameter><initializer>&false;</initializer></methodparam>
25
24
</methodsynopsis>
26
-
<methodsynopsis role="DateTimeInterface">
27
-
<modifier>public</modifier> <type>DateInterval</type><methodname>DateTimeInterface::diff</methodname>
28
-
<methodparam><type>DateTimeInterface</type><parameter>datetime2</parameter></methodparam>
29
-
<methodparam choice="opt"><type>bool</type><parameter>absolute</parameter><initializer>false</initializer></methodparam>
25
+
<methodsynopsis role="DateTime">
26
+
<modifier>public</modifier> <type>DateInterval</type><methodname>DateTime::diff</methodname>
27
+
<methodparam><type>DateTimeInterface</type><parameter>targetObject</parameter></methodparam>
28
+
<methodparam choice="opt"><type>bool</type><parameter>absolute</parameter><initializer>&false;</initializer></methodparam>
30
29
</methodsynopsis>
31
30
<para>&style.procedural;</para>
32
-
<methodsynopsis role="procedural">
31
+
<methodsynopsis>
33
32
<type>DateInterval</type><methodname>date_diff</methodname>
34
-
<methodparam><type>DateTimeInterface</type><parameter>datetime1</parameter></methodparam>
35
-
<methodparam><type>DateTimeInterface</type><parameter>datetime2</parameter></methodparam>
36
-
<methodparam choice="opt"><type>bool</type><parameter>absolute</parameter><initializer>false</initializer></methodparam>
33
+
<methodparam><type>DateTimeInterface</type><parameter>baseObject</parameter></methodparam>
34
+
<methodparam><type>DateTimeInterface</type><parameter>targetObject</parameter></methodparam>
35
+
<methodparam choice="opt"><type>bool</type><parameter>absolute</parameter><initializer>&false;</initializer></methodparam>
37
36
</methodsynopsis>
38
37
<para>
39
38
Returns the difference between two <classname>DateTimeInterface</classname>
...
...
@@ -66,22 +65,36 @@
66
65
<refsect1 role="returnvalues">
67
66
&reftitle.returnvalues;
68
67
<para>
69
-
The <classname>DateInterval</classname> object representing the
70
-
difference between the two dates&return.falseforfailure;.
68
+
The <classname>DateInterval</classname> object represents the
69
+
difference between the two dates.
70
+
</para>
71
+
<para>
72
+
The return value more specifically represents the clock-time interval to
73
+
apply to the original object (<parameter>$this</parameter> or
74
+
<parameter>$originObject</parameter>) to arrive at the
75
+
<parameter>$targetObject</parameter>. This process is not always
76
+
reversible.
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.
71
84
</para>
72
85
</refsect1>
73
86

74
87
<refsect1 role="examples">
75
88
&reftitle.examples;
76
89
<example>
77
-
<title><function>DateTime::diff</function> example</title>
90
+
<title><function>DateTimeImmutable::diff</function> example</title>
78
91
<para>&style.oop;</para>
79
92
<programlisting role="php">
80
93
<![CDATA[
81
94
<?php
82
-
$datetime1 = new DateTime('2009-10-11');
83
-
$datetime2 = new DateTime('2009-10-13');
84
-
$interval = $datetime1->diff($datetime2);
95
+
$origin = new DateTimeImmutable('2009-10-11');
96
+
$target = new DateTimeImmutable('2009-10-13');
97
+
$interval = $origin->diff($target);
85
98
echo $interval->format('%R%a days');
86
99
?>
87
100
]]>
...
...
@@ -90,9 +103,9 @@ echo $interval->format('%R%a days');
90
103
<programlisting role="php">
91
104
<![CDATA[
92
105
<?php
93
-
$datetime1 = date_create('2009-10-11');
94
-
$datetime2 = date_create('2009-10-13');
95
-
$interval = date_diff($datetime1, $datetime2);
106
+
$origin = date_create('2009-10-11');
107
+
$target = date_create('2009-10-13');
108
+
$interval = date_diff($origin, $target);
96
109
echo $interval->format('%R%a days');
97
110
?>
98
111
]]>
...
...
@@ -104,11 +117,60 @@ echo $interval->format('%R%a days');
104
117
]]>
105
118
</screen>
106
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
+

107
168
<example>
108
169
<title><classname>DateTime</classname> object comparison</title>
109
170
<note>
110
171
<para>
111
-
As of PHP 5.2.2, DateTime objects can be compared using
172
+
<classname>DateTimeImmutable</classname> and
173
+
<classname>DateTime</classname> objects can be compared using
112
174
<link linkend="language.operators.comparison">comparison operators</link>.
113
175
</para>
114
176
</note>
...
...
@@ -145,7 +207,6 @@ bool(false)
145
207
</refsect1>
146
208

147
209
</refentry>
148
-

149
210
<!-- Keep this comment at the end of the file
150
211
Local variables:
151
212
mode: sgml
152
213



Tools (Brazilian Portuguese Manual)