Issue #2028499 by tsphethean, damiankloip, dawehner: Drupal_sort_weight()...

Issue #2028499 by tsphethean, damiankloip, dawehner: Drupal_sort_weight() should be converted to a class.

core/includes/common.inc

@@ -2,6 +2,7 @@
 
 use Drupal\Component\Utility\Crypt;
 use Drupal\Component\Utility\Json;
+use Drupal\Component\Utility\SortArray;
 use Drupal\Component\Utility\String;
 use Drupal\Component\Utility\Tags;
 use Drupal\Component\Utility\Url;
@@ -4273,14 +4274,16 @@ function drupal_render_cid_create($elements) {
  *   that optionally include a '#weight' key.
  * @param $b
  *   Second item for comparison.
+ *
+ * @return int
+ *   The comparison result for uasort().
+ *
+ * @see \Drupal\Component\Utility\SortArray::sortByWeightProperty()
+ *
+ * @deprecated as of Drupal 8.0. Use SortArray::sortByWeightProperty() instead.
  */
 function element_sort($a, $b) {
-  $a_weight = (is_array($a) && isset($a['#weight'])) ? $a['#weight'] : 0;
-  $b_weight = (is_array($b) && isset($b['#weight'])) ? $b['#weight'] : 0;
-  if ($a_weight == $b_weight) {
-    return 0;
-  }
-  return ($a_weight < $b_weight) ? -1 : 1;
+  return SortArray::sortByWeightProperty($a, $b);
 }
 
 /**
@@ -4295,11 +4298,16 @@ function element_sort($a, $b) {
  *   that optionally include a '#title' key.
  * @param $b
  *   Second item for comparison.
+ *
+ * @return int
+ *   The comparison result for uasort().
+ *
+ * @see \Drupal\Component\Utility\SortArray::sortByTitleProperty()
+ *
+ * @deprecated as of Drupal 8.0. Use SortArray::sortByTitleProperty() instead.
  */
 function element_sort_by_title($a, $b) {
-  $a_title = (is_array($a) && isset($a['#title'])) ? $a['#title'] : '';
-  $b_title = (is_array($b) && isset($b['#title'])) ? $b['#title'] : '';
-  return strnatcasecmp($a_title, $b_title);
+  return SortArray::sortByTitleProperty($a, $b);
 }
 
 /**
@@ -4357,14 +4365,16 @@ function element_info_property($type, $property_name, $default = NULL) {
  *   element, a default value of 0 will be used.
  * @param $b
  *   Second item for comparison.
+ *
+ * @return int
+ *   The comparison result for uasort().
+ *
+ * @see \Drupal\Component\Utility\SortArray::sortByWeightElement()
+ *
+ * @deprecated as of Drupal 8.0. Use SortArray::sortByWeightElement() instead.
  */
 function drupal_sort_weight($a, $b) {
-  $a_weight = (is_array($a) && isset($a['weight'])) ? $a['weight'] : 0;
-  $b_weight = (is_array($b) && isset($b['weight'])) ? $b['weight'] : 0;
-  if ($a_weight == $b_weight) {
-    return 0;
-  }
-  return ($a_weight < $b_weight) ? -1 : 1;
+  return SortArray::sortByWeightElement((array) $a, (array) $b);
 }
 
 /**
@@ -4377,15 +4387,16 @@ function drupal_sort_weight($a, $b) {
  *   that optionally include a 'title' key.
  * @param $b
  *   Second item for comparison.
+ *
+ * @return int
+ *   The comparison result for uasort().
+ *
+ * @see \Drupal\Component\Utility\SortArray::sortByTitleElement()
+ *
+ * @deprecated as of Drupal 8.0. Use SortArray::sortByTitleElement() instead.
  */
 function drupal_sort_title($a, $b) {
-  if (!isset($b['title'])) {
-    return -1;
-  }
-  if (!isset($a['title'])) {
-    return 1;
-  }
-  return strcasecmp($a['title'], $b['title']);
+  return SortArray::sortByTitleElement($a, $b);
 }
 
 /**

core/lib/Drupal/Component/Utility/SortArray.php

+<?php
+
+/**
+ * @file
+ * Contains \Drupal\Component\Utility\SortArray.
+ */
+
+namespace Drupal\Component\Utility;
+
+/**
+ * Provides generic array sorting helper methods.
+ */
+class SortArray {
+
+  /**
+   * Sorts a structured array by the 'weight' element.
+   *
+   * Note that the sorting is by the 'weight' array element, not by the render
+   * element property '#weight'.
+   *
+   * Callback for uasort() used in various functions.
+   *
+   * @param array $a
+   *   First item for comparison. The compared items should be associative
+   *   arrays that optionally include a 'weight' element. For items without a
+   *   'weight' element, a default value of 0 will be used.
+   * @param array $b
+   *   Second item for comparison.
+   *
+   * @return int
+   *   The comparison result for uasort().
+   */
+  public static function sortByWeightElement(array $a, array $b) {
+    return static::sortByKeyInt($a, $b, 'weight');
+  }
+
+  /**
+   * Sorts a structured array by '#weight' property.
+   *
+   * Callback for uasort() within element_children().
+   *
+   * @param array $a
+   *   First item for comparison. The compared items should be associative
+   *   arrays that optionally include a '#weight' key.
+   * @param array $b
+   *   Second item for comparison.
+   *
+   * @return int
+   *   The comparison result for uasort().
+   */
+  public static function sortByWeightProperty($a, $b) {
+    return static::sortByKeyInt($a, $b, '#weight');
+  }
+
+  /**
+   * Sorts a structured array by 'title' key (no # prefix).
+   *
+   * Callback for uasort() within system_admin_index().
+   *
+   * @param array $a
+   *   First item for comparison. The compared items should be associative arrays
+   *   that optionally include a 'title' key.
+   * @param array $b
+   *   Second item for comparison.
+   *
+   * @return int
+   *   The comparison result for uasort().
+   */
+  public static function sortByTitleElement($a, $b) {
+    return static::sortByKeyString($a, $b, 'title');
+  }
+
+  /**
+   * Sorts a structured array by '#title' property.
+   *
+   * Callback for uasort() within:
+   * - system_modules()
+   * - theme_simpletest_test_table()
+   *
+   * @param array $a
+   *   First item for comparison. The compared items should be associative arrays
+   *   that optionally include a '#title' key.
+   * @param array $b
+   *   Second item for comparison.
+   *
+   * @return int
+   *   The comparison result for uasort().
+   */
+   public static function sortByTitleProperty($a, $b) {
+     return static::sortByKeyString($a, $b, '#title');
+   }
+
+  /**
+   * Sorts a string array item by an arbitrary key.
+   *
+   * @param array $a
+   *   First item for comparison.
+   * @param array $b
+   *   Second item for comparison.
+   * @param string $key
+   *   The key to use in the comparison.
+   *
+   * @return int
+   *   The comparison result for uasort().
+   */
+  public static function sortByKeyString($a, $b, $key) {
+    $a_title = (is_array($a) && isset($a[$key])) ? $a[$key] : '';
+    $b_title = (is_array($b) && isset($b[$key])) ? $b[$key] : '';
+
+    return strnatcasecmp($a_title, $b_title);
+  }
+
+  /**
+   * Sorts an integer array item by an arbitrary key.
+   *
+   * @param array $a
+   *   First item for comparison.
+   * @param array $b
+   *   Second item for comparison.
+   * @param string $key
+   *   The key to use in the comparison.
+   *
+   * @return int
+   *   The comparison result for uasort().
+   */
+  public static function sortByKeyInt($a, $b, $key) {
+    $a_weight = (is_array($a) && isset($a[$key])) ? $a[$key] : 0;
+    $b_weight = (is_array($b) && isset($b[$key])) ? $b[$key] : 0;
+
+    if ($a_weight == $b_weight) {
+      return 0;
+    }
+
+    return ($a_weight < $b_weight) ? -1 : 1;
+  }
+
+}

core/tests/Drupal/Tests/Component/Utility/SortArrayTest.php

+<?php
+
+/**
+ * @file
+ * Contains \Drupal\Tests\Component\Utility\SortArrayTest.
+ */
+
+namespace Drupal\Tests\Component\Utility;
+
+use Drupal\Tests\UnitTestCase;
+use Drupal\Component\Utility\SortArray;
+
+/**
+ * Tests the MapArray system.
+ *
+ * @see \Drupal\Component\Utility\SortArray
+ */
+class SortArrayTest extends UnitTestCase {
+
+  public static function getInfo() {
+    return array(
+      'name' => 'SortArray test',
+      'description' => 'Test that the SortArray functions work properly.',
+      'group' => 'Common',
+    );
+  }
+
+  /**
+   * Tests SortArray::sortByWeightElement() input against expected output.
+   *
+   * @dataProvider providerSortByWeightElement
+   *
+   * @param array $a
+   *   The first input array for the SortArray::sortByWeightElement() method.
+   * @param array $b
+   *   The second input array for the SortArray::sortByWeightElement().
+   * @param integer $expected
+   *   The expected output from calling the method.
+   *
+   * @see Drupal\Component\Utility\SortArray::sortByWeightElement()
+   * @see Drupal\Tests\Component\Utility\SortArrayTest::providersortByWeightElement()
+   */
+  public function testSortByWeightElement($a, $b, $expected) {
+    $result = SortArray::sortByWeightElement($a, $b);
+    $this->assertEquals($expected, $result);
+  }
+
+  /**
+   * Data provider for SortArray::sortByWeightElement().
+   *
+   * @return array
+   *   An array of tests, matching the parameter inputs for
+   *   testSortByWeightElement.
+   *
+   * @see \Drupal\Component\Utility\SortArray::sortByWeightElement()
+   * @see \Drupal\Tests\Component\Utility\SortArrayTest::testSortByWeightElement()
+   */
+  public function providerSortByWeightElement() {
+    $tests = array();
+
+    // Weights set and equal.
+    $tests[] = array(
+      array('weight' => 1),
+      array('weight' => 1),
+      0
+    );
+
+    // Weights set and $a is less (lighter) than $b.
+    $tests[] = array(
+      array('weight' => 1),
+      array('weight' => 2),
+      -1
+    );
+
+    // Weights set and $a is greater (heavier) than $b.
+    $tests[] = array(
+      array('weight' => 2),
+      array('weight' => 1),
+      1
+    );
+
+    // Weights not set.
+    $tests[] = array(
+      array(),
+      array(),
+      0
+    );
+
+    // Weights for $b not set.
+    $tests[] = array(
+      array('weight' => 1),
+      array(),
+      1
+    );
+
+    // Weights for $a not set.
+    $tests[] = array(
+      array(),
+      array('weight' => 1),
+      -1
+    );
+
+    return $tests;
+  }
+
+  /**
+   * Tests SortArray::sortByWeightProperty() input against expected output.
+   *
+   * @dataProvider providerSortByWeightProperty
+   *
+   * @param array $a
+   *   The first input array for the SortArray::sortByWeightProperty() method.
+   * @param array $b
+   *   The second input array for the SortArray::sortByWeightProperty().
+   * @param integer $expected
+   *   The expected output from calling the method.
+   *
+   * @see Drupal\Component\Utility\SortArray::sortByWeightProperty()
+   * @see Drupal\Tests\Component\Utility\SortArrayTest::SortByWeightProperty()
+   */
+  public function testSortByWeightProperty($a, $b, $expected) {
+    $result = SortArray::sortByWeightProperty($a, $b);
+    $this->assertEquals($expected, $result);
+  }
+
+  /**
+   * Data provider for SortArray::sortByWeightProperty().
+   *
+   * @return array
+   *   An array of tests, matching the parameter inputs for
+   *   testSortByWeightProperty.
+   *
+   * @see \Drupal\Component\Utility\SortArray::sortByWeightProperty()
+   * @see \Drupal\Tests\Component\Utility\SortArrayTest::testSortByWeightProperty()
+   */
+  public function providerSortByWeightProperty() {
+    $tests = array();
+
+    // Weights set and equal.
+    $tests[] = array(
+      array('#weight' => 1),
+      array('#weight' => 1),
+      0
+    );
+
+    // Weights set and $a is less (lighter) than $b.
+    $tests[] = array(
+      array('#weight' => 1),
+      array('#weight' => 2),
+      -1
+    );
+
+    // Weights set and $a is greater (heavier) than $b.
+    $tests[] = array(
+      array('#weight' => 2),
+      array('#weight' => 1),
+      1
+    );
+
+    // Weights not set.
+    $tests[] = array(
+      array(),
+      array(),
+      0
+    );
+
+    // Weights for $b not set.
+    $tests[] = array(
+      array('#weight' => 1),
+      array(),
+      1
+    );
+
+    // Weights for $a not set.
+    $tests[] = array(
+      array(),
+      array('#weight' => 1),
+      -1
+    );
+
+    return $tests;
+  }
+
+  /**
+   * Tests SortArray::sortByTitleElement() input against expected output.
+   *
+   * @dataProvider providerSortByTitleElement
+   *
+   * @param array $a
+   *   The first input item for comparison.
+   * @param array $b
+   *   The second item for comparison.
+   * @param integer $expected
+   *   The expected output from calling the method.
+   *
+   * @see Drupal\Component\Utility\SortArray::sortByTitleElement()
+   * @see Drupal\Tests\Component\Utility\SortArrayTest::providerSortByTitleElement()
+   */
+  public function testSortByTitleElement($a, $b, $expected) {
+    $result = SortArray::sortByTitleElement($a, $b);
+    $this->assertEquals($expected, $result);
+  }
+
+  /**
+   * Data provider for SortArray::sortByTitleElement().
+   *
+   * @return array
+   *   An array of tests, matching the parameter inputs for
+   *   testSortByTitleElement.
+   *
+   * @see \Drupal\Component\Utility\SortArray::sortByTitleElement()
+   * @see \Drupal\Tests\Component\Utility\SortArrayTest::testSortByTitleElement()
+   */
+  public function providerSortByTitleElement() {
+    $tests = array();
+
+    // Titles set and equal.
+    $tests[] = array(
+      array('title' => 'test'),
+      array('title' => 'test'),
+      0
+    );
+
+    // Title $a not set.
+    $tests[] = array(
+      array(),
+      array('title' => 'test'),
+      -4
+    );
+
+    // Title $b not set.
+    $tests[] = array(
+      array('title' => 'test'),
+      array(),
+      4
+    );
+
+    // Titles set but not equal.
+    $tests[] = array(
+      array('title' => 'test'),
+      array('title' => 'testing'),
+      -1
+    );
+
+    // Titles set but not equal.
+    $tests[] = array(
+      array('title' => 'testing'),
+      array('title' => 'test'),
+      1
+    );
+
+    return $tests;
+  }
+
+  /**
+   * Tests SortArray::sortByTitleProperty() input against expected output.
+   *
+   * @dataProvider providerSortByTitleProperty
+   *
+   * @param array $a
+   *   The first input item for comparison.
+   * @param array $b
+   *   The second item for comparison.
+   * @param integer $expected
+   *   The expected output from calling the method.
+   *
+   * @see Drupal\Component\Utility\SortArray::sortByTitleProperty()
+   * @see Drupal\Tests\Component\Utility\SortArrayTest::SortByTitleProperty()
+   */
+  public function testSortByTitleProperty($a, $b, $expected) {
+    $result = SortArray::sortByTitleProperty($a, $b);
+    $this->assertEquals($expected, $result);
+  }
+
+  /**
+   * Data provider for SortArray::sortByTitleProperty().
+   *
+   * @return array
+   *   An array of tests, matching the parameter inputs for
+   *   testSortByTitleProperty.
+   *
+   * @see \Drupal\Component\Utility\SortArray::sortByTitleProperty()
+   * @see \Drupal\Tests\Component\Utility\SortArrayTest::testSortByTitleProperty()
+   */
+  public function providerSortByTitleProperty() {
+    $tests = array();
+
+    // Titles set and equal.
+    $tests[] = array(
+      array('#title' => 'test'),
+      array('#title' => 'test'),
+      0
+    );
+
+    // Title $a not set.
+    $tests[] = array(
+      array(),
+      array('#title' => 'test'),
+      -4
+    );
+
+    // Title $b not set.
+    $tests[] = array(
+      array('#title' => 'test'),
+      array(),
+      4
+    );
+
+    // Titles set but not equal.
+    $tests[] = array(
+      array('#title' => 'test'),
+      array('#title' => 'testing'),
+      -1
+    );
+
+    // Titles set but not equal.
+    $tests[] = array(
+      array('#title' => 'testing'),
+      array('#title' => 'test'),
+      1
+    );
+
+    return $tests;
+  }
+
+}