Laravel Collection Public API: sortBy

sortBy($callback, $options = SORT_REGULAR, $descending = false)

The sortBy method is useful and versatile way to sort collections by some key, or by some value returned by a $callback. The $callback can either be a function that defines two parameters: $value and $key or the $callback can be the name of some key to sort the collection by. The $options parameter allows developers to modify the sorting behavior and the $descending parameter controls whether or not the sortBy method will sort the collection ascending (false) or descending (true). The sortBy method does not modify the original collection instance, but will return a new instance of Collection with the items sorted.

The following collection of imaginary users will be used when demonstrating the features of the sortBy method:

 1<?php
 2 
 3use Illuminate\Support\Collection;
 4 
 5// Create a new collection instance.
 6$collection = new Collection([
 7    [
 8      'name' => 'Sue',
 9      'age'  => 23,
10      'followers' => [
11        'Jim',
12        'Donna'
13      ]
14    ],
15    [
16      'name' => 'Simon',
17      'age' => 38,
18      'followers' => [
19        'Sue'
20      ]
21    ],
22    [
23      'name' => 'Jane',
24      'age' => 25,
25      'followers' => [
26        'Link',
27        'Dave',
28        'Chase'
29      ]
30    ],
31    [
32      'name' => 'Dave',
33      'age' => 19,
34      'followers' => [
35        'Dee Dee',
36        'Stevie'
37      ]
38    ]
39]);

It is possible to sort the $collection by name like so:

1<?php
2 
3// Sort the users by name:
4$sorted = $collection->sortBy('name');

The $sorted variable would now be an instance of Collection and the items would be in the following order:

1Dave
2Jane
3Simon
4Sue

To reverse the order, the following could be used:

1<?php
2 
3$sorted = $collection->sort('name', SORT_REGULAR, true);

The $sorted collection would now be in the following order:

1Sue
2Simon
3Jane
4Dave

The users can also be sorted by the number of followers they have. To accomplish this, a callback function must be used:

1<?php
2 
3// Sort the users by the number of followers.
4$sorted = $collection->sortBy(function($value, $key) {
5    return count($value['followers']);
6});

The $sorted collection would now be in the following order:

1Simon
2Sue
3Dave
4Jane

Of course, it is often desirable to see which users have the most followers. To do this, use the same techniques as before to change the sort order to descending:

1<?php
2 
3// Sort the users by the number of followers.
4$sorted = $collection->sortBy(function($value, $key) {
5    return count($value['followers']);
6}, SORT_REGULAR, true);

#sortBy Options

The $options parameter allows developers to change the sorting behavior of the sortBy method. The accepted options are the same options that are defined for PHP's sort function. The following collection instance will be used throughout this section when describing the behavior of the various options:

 1<?php
 2 
 3use Illuminate\Support\Collection;
 4 
 5/**
 6 * A simple class to represent an animal.
 7 *
 8 * Its only purpose to accept the name of the
 9 * animal and return it when the object
10 * instance is cast to a string.
11 */
12class Animal {
13 
14  /**
15   * The name of the animal.
16   *
17   * @var string
18   */
19  private $name = '';
20 
21  public function __construct($name) {
22    $this->name = $name;
23  }
24 
25  public function __toString() {
26    return $this->name;
27  }
28 
29}
30 
31// Create a new collection instance.
32$collection = new Collection([
33   0 => 'a2.txt',
34   1 => 'a1.txt',
35   2 => 'a4.txt',
36   3 => new Animal('KANGAROO'),
37   4 => new Animal('kangaroo'),
38   5 => 'a3.txt',
39   6 => 6,
40   7 => 5,
41   8 => new Animal('macaw'),
42   9 => 'candice',
43  10 => 'bob',
44  11 => 'alice',
45  12 => new Animal('zebra')
46]);

The $collection contains a diverse range of items. It contains strings, integers and a few Animal instances. The keys of each item have also been explicitly set. This will make it easier to keep track of where each item has moved after the collection is sorted.

The following sort flags are available when using the sortBy method:

#Sorting Flag Comparison Table

The following tables will show how the different sorting flags change the sorting of the previously made $collection. Each sorting flag has its own section, which will follow this section. The first table shows the key and its associated value from the original collection, which can be used to locate the original item from the table that follows. The table that follows shows each sorting flag and the sorting order that would result from using that sorting flag. The collection was sorted by using the string representation of the item's value.

#Collection Keys and Values

#Sorting Flag Result Comparison

#SORT_NUMERIC

The SORT_NUMERIC treats each item as a number when doing the comparison. The following code example shows how to use the SORT_NUMERIC flag when sorting the $collection created previously (the callback function will return the string representation of the item):

1<?php
2 
3// Sort the collection using the SORT_NUMERIC flag.
4$sorted = $collection->sortBy(function($value, $key) {
5  return (string) $value;
6}, SORT_NUMERIC);

The following table will use each item's key to represent the new sort order. It will compare the original collection order, the order when using the SORT_REGULAR flag and the order when using the SORT_NUMERIC flag.

#SORT_NUMERIC Result Comparision

#SORT_STRING

The SORT_STRING treats each item as a string when doing the comparison. The following code example shows how to use the SORT_STRING flag when sorting the $collection created previously (the callback function will return the string representation of the item):

1<?php
2 
3// Sort the collection using the SORT_STRING flag.
4$sorted = $collection->sortBy(function($value, $key) {
5  return (string) $value;
6}, SORT_STRING);

The following table will use each item's key to represent the new sort order. It will compare the original collection order, the order when using the SORT_REGULAR flag and the order when using the SORT_STRING flag.

#SORT_STRING Result Comparison

#SORT_STRING and SORT_FLAG_CASE for Case Insensitivity

The SORT_FLAG_CASE flag can be combined with the SORT_STRING flag to treat each item as a string while also ignored the case of each item. The following example shows how to use the SORT_STRING with the SORT_FLAG_CASE flag when sorting the $collection created previously (the callback function will return the string representation of the item):

1<?php
2 
3// Sort the collection using the SORT_STRING and the
4// SORT_FLAG_CASE flags.
5$sorted = $collection->sortBy(function($value, $key) {
6  return (string) $value;
7}, SORT_STRING | SORT_FLAG_CASE);

The following table will use each item's key to represent the new sort order. It will compare the original collection order, the order when using the SORT_STRING flag and the order when using the SORT_STRING combined with the SORT_FLAG_CASE flag.

#SORT_STRING | SORT_FLAG_CASE Result Comparison

#SORT_LOCALE_STRING

The SORT_LOCALE_STRING treats each item as a string, while also taking into account the current locale, when doing the comparison. The following code example shows how to use the SORT_LOCALE_STRING flag when sorting the $collection created previously (the callback function will return the string representation of the item):

1<?php
2 
3// Sort the collection using the SORT_LOCALE_STRING flag.
4$sorted = $collection->sortBy(function($value, $key) {
5  return (string) $value;
6}, SORT_LOCALE_STRING);

The following table will use each item's key to represent the new sort order. It will compare the original collection order, the order when using the SORT_REGULAR flag and the order when using the SORT_LOCALE_STRING flag.

#SORT_LOCALE_STRING Result Comparison

#SORT_NATURAL

The SORT_NATURAL treats each item as a string while using a "natural ordering" algorithm to perform the sorting. The following code example shows how to use the SORT_NATURAL flag when sorting the $collection created previously (the callback function will return the string representation of the item):

1<?php
2 
3// Sort the collection using the SORT_NATURAL flag.
4$sorted = $collection->sortBy(function($value, $key) {
5  return (string) $value;
6}, SORT_NATURAL);

The following table will use each item's key to represent the new sort order. It will compare the original collection order, the order when using the SORT_REGULAR flag and the order when using the SORT_NATURAL flag.

#SORT_NATURAL Result Comparison

#SORT_NATURAL and SORT_FLAG_CASE for Case Insensitivity

The SORT_FLAG_CASE flag can be combined with the SORT_NATURAL flag to treat each item as a string while also ignored the case of each item. The following example shows how to use the SORT_NATURAL with the SORT_FLAG_CASE flag when sorting the $collection created previously (the callback function will return the string representation of the item):

1<?php
2 
3// Sort the collection using the SORT_NATURAL and the
4// SORT_FLAG_CASE flags.
5$sorted = $collection->sortBy(function($value, $key) {
6  return (string) $value;
7}, SORT_NATURAL | SORT_FLAG_CASE);

The following table will use each item's key to represent the new sort order. It will compare the original collection order, the order when using the SORT_NATURAL flag and the order when using the SORT_NATURAL combined with the SORT_FLAG_CASE flag.

#SORT_NATURAL | SORT_FLAG_CASE Result Comparison

∎