From 3d9dad29c75a70e7985ed595dfa2a836e61418da Mon Sep 17 00:00:00 2001
From: "Christoph M. Becker" <cmbecker69@gmx.de>
Date: Mon, 23 May 2022 11:31:55 +0200
Subject: [PATCH] Fix bug #67034: Unable to compare DateInterval instances with
 == operator

Closes GH-1590.
---
 language/operators.xml              | 14 ++++++++++++--
 reference/datetime/dateinterval.xml | 12 ++++++++++++
 2 files changed, 24 insertions(+), 2 deletions(-)

diff --git a/language/operators.xml b/language/operators.xml
index b8409dc3a5..33f5dd8097 100644
--- a/language/operators.xml
+++ b/language/operators.xml
@@ -1685,7 +1685,7 @@ echo $a <=> $b; // 1
        <entry><type>object</type></entry>
        <entry><type>object</type></entry>
        <entry>Built-in classes can define its own comparison, different classes
-        are uncomparable, same class see <link
+        are incomparable, same class see <link
         linkend="language.oop5.object-comparison">Object Comparison</link>
        </entry>
       </row>
@@ -1698,7 +1698,7 @@ echo $a <=> $b; // 1
        <entry><type>array</type></entry>
        <entry><type>array</type></entry>
        <entry>Array with fewer members is smaller, if key from operand 1 is not
-        found in operand 2 then arrays are uncomparable, otherwise - compare
+        found in operand 2 then arrays are incomparable, otherwise - compare
         value by value (see following example)</entry>
       </row>
       <row>
@@ -1786,6 +1786,16 @@ function standard_array_compare($op1, $op2)
     </simpara>
    </note>
 
+   <sect2 xml:id="language.operators.comparison.incomparable">
+    <title>Incomparable Values</title>
+    <simpara>
+     While identity comparison (<literal>===</literal> and <literal>!==</literal>)
+     can be applied to arbitrary values, the other comparison operators should only be
+     applied to comparable values. The result of comparing incomparable values is
+     undefined, and should not be relied upon.
+    </simpara>
+   </sect2>
+
    <sect2 role="seealso">
     &reftitle.seealso;
     <para>
diff --git a/reference/datetime/dateinterval.xml b/reference/datetime/dateinterval.xml
index 9f8e9a0a02..fc5a85f944 100644
--- a/reference/datetime/dateinterval.xml
+++ b/reference/datetime/dateinterval.xml
@@ -28,6 +28,11 @@
     is by calculating the difference between two date/time objects through
     <function>DateTimeInterface::diff</function>.
    </para>
+   <para>
+    Since there is no well defined way to compare date intervals,
+    <classname>DateInterval</classname> instances are
+    <link linkend="language.operators.comparison.incomparable">incomparable</link>.
+   </para>
   </section>
 <!-- }}} -->
 
@@ -201,6 +206,13 @@
        </row>
       </thead>
       <tbody>
+      <row>
+       <entry>7.4.0</entry>
+       <entry>
+        <classname>DateInterval</classname> instances are incomparable now;
+        previously, all <classname>DateInterval</classname> instances were considered equal.
+       </entry>
+      </row>
        <row>
         <entry>7.1.0</entry>
         <entry>The <varname>f</varname> property was added.</entry>