function backdrop_sort

Sort an array based on user-provided keys within that array.

// Sort by a single numeric key:
backdrop_sort($my_array, array('weight' => SORT_NUMERIC));

// Shorthand sort by a numeric key:
backdrop_sort($my_array, array('weight'));

// Sort by numeric and string keys.
backdrop_sort($my_array, array('weight' => SORT_NUMERIC, 'title' => SORT_STRING));

@since 1.9.0 The $dir parameter was added.

Parameters

array $array: The input array to be sorted.

array $keys: An array of keys to sort by. Values must be PHP sorting type flags, either SORT_NUMERIC or SORT_STRING, and default to SORT_NUMERIC if an unindexed array is passed in.

string $dir: The sort direction. Values must be either SORT_ASC or SORT_DESC.

Example usage:

File

core/includes/common.inc, line 7335

Common functions that many Backdrop modules will need to reference.

Code

function backdrop_sort(array &$array, array $keys = array('weight'), $dir = SORT_ASC) {
  // Don't sort empty arrays.
  if (empty($array)) {
    return;
  }

  // Prefix array keys to prevent numeric keys being re-indexed (and un-prefix
  // them again after sorting).
  foreach ($array as $key => $value) {
    $prefixed['#' . $key] = $value;
  }
  $array = $prefixed;
  unset($prefixed);

  // Ensure all keys have a sort value.
  $new_keys = array();
  foreach ($keys as $key => $key_sort) {
    if (is_string($key_sort) && is_int($key)) {
      $new_keys[$key_sort] = SORT_NUMERIC;
    }
    else {
      if ($key_sort === SORT_NUMERIC || $key_sort === SORT_STRING) {
        $new_keys[$key] = $key_sort;
      }
      else {
        // Fallback behavior for unexpected values. Untranslated to allow this
        // function to be used anywhere within Backdrop.
        $new_keys[$key] = SORT_NUMERIC;
        trigger_error('backdrop_sort() expects the second parameter to be an array keyed by strings and each value of the array to be either SORT_NUMERIC or SORT_STRING.', E_USER_WARNING);
      }
    }
  }
  $keys = $new_keys;

  // Create an array to use for sorting by each key.
  $sort = array();
  foreach ($array as $k => $v) {
    $v = (array) $v;
    foreach ($keys as $key => $key_sort) {
      if (isset($v[$key])) {
        $sort[$key][$k] = ($key_sort === SORT_STRING) ? backdrop_strtolower($v[$key]) : $v[$key];
      }
      else {
        $sort[$key][$k] = ($key_sort === SORT_STRING) ? '' : 0;
      }
    }
  }

  // Prepare an array of parameters for use with array_multisort().
  $param = array();
  foreach ($keys as $key => $key_sort) {
    $param[] = $sort[$key];
    $param[] = $dir;
    $param[] = $key_sort;
  }
  // Add the array we want to actually sort at the end (by reference).
  $param[] = &$array;

  // Perform the sort.
  call_user_func_array('array_multisort', $param);

  // Un-prefix array keys.
  foreach ($array as $key => $value) {
    $unprefixed[substr($key, 1)] = $value;
  }
  $array = $unprefixed;
  unset($unprefixed);
}