Use a sorting algorithm that's as close to upstream as possible

It's impossible for us to match all browsers exactly (since the way that
elements that compare as equal as sorted is implementation-defined in
JavaScript), but this gets us pretty close.

src/Matcher.php

@@ -31,20 +31,48 @@ public function getMatches($password, array $userInputs = [])
                 $matches = array_merge($matches, $matched);
             }
         }
+
+        self::usortStable($matches, [$this, 'compareMatches']);
         return $matches;
     }
 
     /**
-     * @param Match $a
-     * @param Match $b
+     * A stable implementation of usort().
+     *
+     * Whether or not the sort() function in JavaScript is stable or not is implementation-defined.
+     * This means it's impossible for us to match all browsers exactly, but since most browsers implement sort() using
+     * a stable sorting algorithm, we'll get the highest rate of accuracy by using a stable sort in our code as well.
+     *
+     * This function taken from https://github.com/vanderlee/PHP-stable-sort-functions
+     * Copyright © 2015-2018 Martijn van der Lee (http://martijn.vanderlee.com). MIT License applies.
+     *
+     * @param array $array
+     * @param callable $value_compare_func
+     * @return bool
      */
-    public static function sortMatches($a, $b)
+    public static function usortStable(array &$array, $value_compare_func)
+    {
+        $index = 0;
+        foreach ($array as &$item) {
+            $item = array($index++, $item);
+        }
+        $result = usort($array, function ($a, $b) use ($value_compare_func) {
+            $result = call_user_func($value_compare_func, $a[1], $b[1]);
+            return $result == 0 ? $a[0] - $b[0] : $result;
+        });
+        foreach ($array as &$item) {
+            $item = $item[1];
+        }
+        return $result;
+    }
+
+    public static function compareMatches(Match $a, Match $b)
     {
-        if ($a->begin != $b->begin) {
-            return $a->begin - $b->begin;
-        } else {
-            return $a->end - $b->end;
+        $beginDiff = $a->begin - $b->begin;
+        if ($beginDiff) {
+            return $beginDiff;
         }
+        return $a->end - $b->end;
     }
 
     /**

src/Matchers/DateMatch.php

@@ -2,6 +2,8 @@
 
 namespace ZxcvbnPhp\Matchers;
 
+use ZxcvbnPhp\Matcher;
+
 class DateMatch extends Match
 {
 
@@ -100,6 +102,7 @@ public static function match($password, array $userInputs = [])
         foreach ($dates as $date) {
             $matches[] = new static($password, $date['begin'], $date['end'], $date['token'], $date);
         }
+        Matcher::usortStable($matches, [Matcher::class, 'compareMatches']);
         return $matches;
     }
 

src/Matchers/DictionaryMatch.php

@@ -2,6 +2,8 @@
 
 namespace ZxcvbnPhp\Matchers;
 
+use ZxcvbnPhp\Matcher;
+
 class DictionaryMatch extends Match
 {
 
@@ -58,6 +60,7 @@ public static function match($password, array $userInputs = [], $rankedDictionar
                 $matches[] = new static($password, $result['begin'], $result['end'], $result['token'], $result);
             }
         }
+        Matcher::usortStable($matches, [Matcher::class, 'compareMatches']);
         return $matches;
     }
 

src/Matchers/L33tMatch.php

@@ -2,6 +2,8 @@
 
 namespace ZxcvbnPhp\Matchers;
 
+use ZxcvbnPhp\Matcher;
+
 /**
  * Class L33tMatch extends DictionaryMatch to translate l33t into dictionary words for matching.
  * @package ZxcvbnPhp\Matchers
@@ -73,6 +75,7 @@ public static function match($password, array $userInputs = [], $rankedDictionar
             }
         }
 
+        Matcher::usortStable($matches, [Matcher::class, 'compareMatches']);
         return $matches;
     }
 

src/Matchers/ReverseDictionaryMatch.php

@@ -2,6 +2,8 @@
 
 namespace ZxcvbnPhp\Matchers;
 
+use ZxcvbnPhp\Matcher;
+
 class ReverseDictionaryMatch extends DictionaryMatch
 {
     /** @var bool Whether or not the matched word was reversed in the token. */
@@ -28,8 +30,7 @@ public static function match($password, array $userInputs = [], $rankedDictionar
             $match->begin = mb_strlen($password) - 1 - $match->end;
             $match->end = mb_strlen($password) - 1 - $tempBegin;
         }
-
-        usort($matches, ['ZxcvbnPhp\Matcher', 'sortMatches']);
+        Matcher::usortStable($matches, [Matcher::class, 'compareMatches']);
         return $matches;
     }
 

src/Matchers/SpatialMatch.php

@@ -2,6 +2,8 @@
 
 namespace ZxcvbnPhp\Matchers;
 
+use ZxcvbnPhp\Matcher;
+
 class SpatialMatch extends Match
 {
     const SHIFTED_CHARACTERS = '~!@#$%^&*()_+QWERTYUIOP{}|ASDFGHJKL:"ZXCVBNM<>?';
@@ -45,6 +47,7 @@ public static function match($password, array $userInputs = [], array $graphs =
                 $matches[] = new static($password, $result['begin'], $result['end'], $result['token'], $result);
             }
         }
+        Matcher::usortStable($matches, [Matcher::class, 'compareMatches']);
         return $matches;
     }
 

src/Matchers/YearMatch.php

@@ -2,6 +2,8 @@
 
 namespace ZxcvbnPhp\Matchers;
 
+use ZxcvbnPhp\Matcher;
+
 class YearMatch extends Match
 {
 
@@ -24,6 +26,7 @@ public static function match($password, array $userInputs = [])
         foreach ($groups as $captures) {
             $matches[] = new static($password, $captures[1]['begin'], $captures[1]['end'], $captures[1]['token']);
         }
+        Matcher::usortStable($matches, [Matcher::class, 'compareMatches']);
         return $matches;
     }