[RFC] User-defined object comparison

NEWS

@@ -22,6 +22,8 @@ PDO_Firebird:
     logging. (Philip Prindeville)
   . Fixed bug #63217 (Constant numeric strings become integers when used as
     ArrayAccess offset). (Rudi Theunissen, Dmitry)
+  . Added user-defined object comparison. 
+    (https://wiki.php.net/rfc/object-comparison) (Rudi Theunissen)
 
 - DOM:
   . Fixed bug #76285 (DOMDocument::formatOutput attribute sometimes ignored).

UPGRADING

@@ -247,6 +247,30 @@ Core:
     are available under Linux, FreeBSD, Windows, Mac, SunOS, AIX and their
     derivatives. If no required timers are provided by a corresponding
     platform, the function returns false.
+  . Added two new magic methods: __compareTo and __equals. Classes may choose to
+    implement these to define relative natural ordering and equality, which 
+    affects functions like in_array() and sort(), and comparison operators: 
+    <, >, <=, >=, <=>, ==, !=. The behaviour of === and !== has not changed.
+    Classes that do not implement these methods will continue to be compared 
+    according to the rules that were introduced in PHP 5. 
+    (RFC: https://wiki.php.net/rfc/object-comparison)
+
+
+    +Changes to object comparison behaviour
++--------------------------------------
++
++* Classes may now implement a Comparable interface to override how objects are
++  compared to other values. If implemented, the class must implement a public
++  compareTo() method with the signature:
++
++      public function compareTo($other)
++
++  This method must return a negative integer to signal that the object is less
++  than $other, zero to signal that the object is equal to $other, or a positive
++  integer to signal that the object is greater than $other.
++
++  Objects that don't implement Comparable will continue to be compared
++  according to the rules used in PHP 5.
 
 Date:
   . Added the DateTime::createFromImmutable() method, which mirrors

Zend/tests/comparisons/__compareTo/Comparable.inc

@@ -0,0 +1,31 @@
+<?php
+
+/**
+ * This is a class that compares by a given $value only. There is also a $decoy
+ * value that makes sure that the tests would fail if `__compareTo` is not used.
+ */
+class Comparable
+{
+    protected $decoy;
+    protected $value;
+
+    public function __construct($value) {
+        $this->decoy = $value * -1;
+        $this->value = $value;
+    }  
+
+    public function __compareTo($other) {
+        if ($other instanceof self) {
+            return $this->value <=> $other->value;
+        }
+
+        /**
+         * Allow comparing to scalar numeric values.
+         */
+        if (is_numeric($other)) {
+            return $this->value <=> $other;
+        }
+
+        throw new Exception("Failed to compare");
+    }
+}

Zend/tests/comparisons/__compareTo/compare-array-func-array-keys.phpt

@@ -0,0 +1,121 @@
+--TEST--
+__compareTo: Called by array_keys which has equality semantics (searching)
+--FILE--
+<?php
+include("Comparable.inc");
+
+$a = new Comparable(1);
+$b = new Comparable(2);
+$c = new Comparable(3);
+
+$array = [
+    'a' => $a, 
+    'b' => $b, 
+    'c' => $c,
+];
+
+var_dump(array_keys($array, $a, $strict = false)); // a
+var_dump(array_keys($array, $b, $strict = false)); // b
+var_dump(array_keys($array, $c, $strict = false)); // c
+
+var_dump(array_keys($array, $a, $strict = true)); // a
+var_dump(array_keys($array, $b, $strict = true)); // b
+var_dump(array_keys($array, $c, $strict = true)); // c
+
+/* Found, because Comparable::__compareTo returned 0 */
+var_dump(array_keys($array, new Comparable(1), $strict = false)); // a
+var_dump(array_keys($array, new Comparable(2), $strict = false)); // b
+var_dump(array_keys($array, new Comparable(3), $strict = false)); // c
+
+/* Not found because strict comparison doesn't call __compareTo */
+var_dump(array_keys($array, new Comparable(1), $strict = true)); 
+var_dump(array_keys($array, new Comparable(2), $strict = true)); 
+var_dump(array_keys($array, new Comparable(3), $strict = true)); 
+
+/* Found, because Comparable::__compareTo returned 0 and we haven't implemented __equals */
+var_dump(array_keys($array, 1, $strict = false)); // a
+var_dump(array_keys($array, 2, $strict = false)); // b
+var_dump(array_keys($array, 3, $strict = false)); // c
+
+/* Not found because strict comparison doesn't call __compareTo */
+var_dump(array_keys($array, 1, $strict = true)); 
+var_dump(array_keys($array, 2, $strict = true)); 
+var_dump(array_keys($array, 3, $strict = true)); 
+
+/* Not found */
+var_dump(array_keys($array, new Comparable(4), $strict = true));
+var_dump(array_keys($array, new Comparable(5), $strict = true));
+
+var_dump(array_keys($array, new Comparable(4), $strict = false));
+var_dump(array_keys($array, new Comparable(5), $strict = false));
+
+?>
+--EXPECT--
+array(1) {
+  [0]=>
+  string(1) "a"
+}
+array(1) {
+  [0]=>
+  string(1) "b"
+}
+array(1) {
+  [0]=>
+  string(1) "c"
+}
+array(1) {
+  [0]=>
+  string(1) "a"
+}
+array(1) {
+  [0]=>
+  string(1) "b"
+}
+array(1) {
+  [0]=>
+  string(1) "c"
+}
+array(1) {
+  [0]=>
+  string(1) "a"
+}
+array(1) {
+  [0]=>
+  string(1) "b"
+}
+array(1) {
+  [0]=>
+  string(1) "c"
+}
+array(0) {
+}
+array(0) {
+}
+array(0) {
+}
+array(1) {
+  [0]=>
+  string(1) "a"
+}
+array(1) {
+  [0]=>
+  string(1) "b"
+}
+array(1) {
+  [0]=>
+  string(1) "c"
+}
+array(0) {
+}
+array(0) {
+}
+array(0) {
+}
+array(0) {
+}
+array(0) {
+}
+array(0) {
+}
+array(0) {
+}

Zend/tests/comparisons/__compareTo/compare-array-func-array-search.phpt

@@ -0,0 +1,71 @@
+--TEST--
+__compareTo: Called by array_search which has equality semantics (searching)
+--FILE--
+<?php
+include("Comparable.inc");
+
+$a = new Comparable(1);
+$b = new Comparable(2);
+$c = new Comparable(3);
+
+$array = [$a, $b, $c];
+
+var_dump(array_search($a, $array, $strict = false)); // 0
+var_dump(array_search($b, $array, $strict = false)); // 1
+var_dump(array_search($c, $array, $strict = false)); // 2
+
+var_dump(array_search($a, $array, $strict = true)); // 0
+var_dump(array_search($b, $array, $strict = true)); // 1
+var_dump(array_search($c, $array, $strict = true)); // 2
+
+/* Found, because Comparable::__compareTo returned 0 */
+var_dump(array_search(new Comparable(1), $array, $strict = false)); // 0
+var_dump(array_search(new Comparable(2), $array, $strict = false)); // 1
+var_dump(array_search(new Comparable(3), $array, $strict = false)); // 2
+
+/* Not found, because not the same instance */
+var_dump(array_search(new Comparable(1), $array, $strict = true)); // false
+var_dump(array_search(new Comparable(2), $array, $strict = true)); // false
+var_dump(array_search(new Comparable(3), $array, $strict = true)); // false
+
+/* Found, because Comparable::__compareTo returned 0 and we haven't implemented __equals */
+var_dump(array_search(1, $array, $strict = false)); // 0
+var_dump(array_search(2, $array, $strict = false)); // 1
+var_dump(array_search(3, $array, $strict = false)); // 2
+
+/* Not found, because strict comparison doesn't call __compareTo */
+var_dump(array_search(1, $array, $strict = true)); // false
+var_dump(array_search(2, $array, $strict = true)); // false
+var_dump(array_search(3, $array, $strict = true)); // false
+
+/* Not found */
+var_dump(array_search(new Comparable(4), $array, $strict = false)); // false
+var_dump(array_search(new Comparable(5), $array, $strict = false)); // false
+
+var_dump(array_search(new Comparable(4), $array, $strict = true)); // false
+var_dump(array_search(new Comparable(5), $array, $strict = true)); // false
+
+?>
+--EXPECT--
+int(0)
+int(1)
+int(2)
+int(0)
+int(1)
+int(2)
+int(0)
+int(1)
+int(2)
+bool(false)
+bool(false)
+bool(false)
+int(0)
+int(1)
+int(2)
+bool(false)
+bool(false)
+bool(false)
+bool(false)
+bool(false)
+bool(false)
+bool(false)

Zend/tests/comparisons/__compareTo/compare-array-func-in-array.phpt

@@ -0,0 +1,71 @@
+--TEST--
+__compareTo: Called by in_array which has equality semantics (searching)
+--FILE--
+<?php
+include("Comparable.inc");
+
+$a = new Comparable(1);
+$b = new Comparable(2);
+$c = new Comparable(3);
+
+$array = [$a, $b, $c];
+
+var_dump(in_array($a, $array, $strict = false)); 
+var_dump(in_array($b, $array, $strict = false)); 
+var_dump(in_array($c, $array, $strict = false)); 
+
+var_dump(in_array($a, $array, $strict = true)); 
+var_dump(in_array($b, $array, $strict = true)); 
+var_dump(in_array($c, $array, $strict = true)); 
+
+/* Found, because Comparable::__compareTo returned 0 */
+var_dump(in_array(new Comparable(1), $array, $strict = false)); 
+var_dump(in_array(new Comparable(2), $array, $strict = false)); 
+var_dump(in_array(new Comparable(3), $array, $strict = false)); 
+
+/* Not found, because not the same instance */
+var_dump(in_array(new Comparable(1), $array, $strict = true));
+var_dump(in_array(new Comparable(2), $array, $strict = true));
+var_dump(in_array(new Comparable(3), $array, $strict = true));
+
+/* Found, because Comparable::__compareTo returned 0 and we haven't implemented __equals */
+var_dump(in_array(1, $array, $strict = false));
+var_dump(in_array(2, $array, $strict = false));
+var_dump(in_array(3, $array, $strict = false));
+
+/* Not found, because strict comparison doesn't call __compareTo */
+var_dump(in_array(1, $array, $strict = true)); 
+var_dump(in_array(2, $array, $strict = true)); 
+var_dump(in_array(3, $array, $strict = true)); 
+
+/* Not found */
+var_dump(in_array(new Comparable(4), $array, $strict = false)); 
+var_dump(in_array(new Comparable(5), $array, $strict = false)); 
+
+var_dump(in_array(new Comparable(4), $array, $strict = true)); 
+var_dump(in_array(new Comparable(5), $array, $strict = true)); 
+
+?>
+--EXPECT--
+bool(true)
+bool(true)
+bool(true)
+bool(true)
+bool(true)
+bool(true)
+bool(true)
+bool(true)
+bool(true)
+bool(false)
+bool(false)
+bool(false)
+bool(true)
+bool(true)
+bool(true)
+bool(false)
+bool(false)
+bool(false)
+bool(false)
+bool(false)
+bool(false)
+bool(false)

Zend/tests/comparisons/__compareTo/compare-array-sort.phpt

@@ -0,0 +1,38 @@
+--TEST--
+__compareTo: Called by array functions with ordering semantics (sorting)
+--FILE--
+<?php
+include("Comparable.inc");
+
+$a = new Comparable(3);
+$b = new Comparable(1);
+$c = new Comparable(2);
+
+$array = [$a, $b, $c];
+
+sort($array);
+
+var_dump($array[0]);
+var_dump($array[1]);
+var_dump($array[2]);
+
+?>
+--EXPECT--
+object(Comparable)#2 (2) {
+  ["decoy":protected]=>
+  int(-1)
+  ["value":protected]=>
+  int(1)
+}
+object(Comparable)#3 (2) {
+  ["decoy":protected]=>
+  int(-2)
+  ["value":protected]=>
+  int(2)
+}
+object(Comparable)#1 (2) {
+  ["decoy":protected]=>
+  int(-3)
+  ["value":protected]=>
+  int(3)
+}