Laravel 5 Collections: Getting the First Collection Element With first

The first method is used to get the first item in a collection, or to get the first item in a collection that matches a set of criteria. A $callback can be supplied to return the first item in the collection that matches a given truth test. Additionally, an optional $default argument can be supplied that will be returned if there are no items that match the given criteria.

#Signature

1public function first(
2    callable $callback = null,
3    $default = null
4);

#Example Use

The following example shows how to get the first item in a collection:

1use Illuminate\Support\Collection;
2 
3// Create a new collection instance.
4$collection = new Collection([
5    'first', 'second', 'third'
6]);
7 
8// first
9$value = $collection->first();

If the collection is empty (having no items), the first method will return null:

1use Illuminate\Support\Collection;
2 
3// Create an empty collection.
4$collection = new Collection([]);
5 
6// null
7$value = $collection->first();

The $default parameter cannot be used when trying to get the first item in an empty collection:

1use Illuminate\Support\Collection;
2 
3// Create an empty collection.
4$collection = new Collection([]);
5 
6// null
7$value = $collection->first(null, 'default-value');

A $callback argument can be passed to provide a truth test when evaluating which item should be returned first:

 1use Illuminate\Support\Collection;
 2 
 3// Create a new collection instance.
 4$collection = new Collection([
 5    'first', 'second', 'third'
 6]);
 7 
 8// second
 9$value = $collection->first(function($value, $key) {
10    return strlen($value) > 5;
11});

The $default parameter can be used in conjunction with the $callback parameter to return a default value when there are no items in a collection that pass the given truth test:

 1use Illuminate\Support\Collection;
 2 
 3// null
 4$value = $collection->first(function($value, $key) {
 5    return strlen($value) > 10;
 6});
 7 
 8// default-value
 9$value = $collection->first(function($value, $key) {
10    return strlen($value) > 10;
11}, 'default-value');

#Using first With Higher Order Messages

The first method can also be used with higher order messaging, which allows us to invoke collection methods and access object instance properties using PHP's property accessors syntax. In the reject section, we created a Product class that was used to reject all products that were not on sale.

We will use the Product class again to use the first method with higher order messaging to retrieve the first product in a collection that is on sale:

 1$products = collect([
 2    [
 3        'name'   => 'Office Chair',
 4        'price'  => 399.99,
 5        'onSale' => true
 6    ],
 7    [
 8        'name'   => 'Desk',
 9        'price'  => 199.34,
10        'onSale' => true
11    ]
12])->transform(function ($item) {
13    $product = new Product;
14    $product->name   = $item['name'];
15    $product->price  = $item['price'];
16    $product->onSale = $item['onSale'];
17 
18    return $product;
19});
20 
21$firstOnSale = $products->first->isOnSale();

After the above code has executed, the $firstOnSale variable would hold a reference to the Product instance representing the office chair.

∎