Laravel 5: Finding the First Occurrence of an Element Matching a Condition With first

Let's begin discussing the first helper method be examining the $callback. The $callback is a function that accepts a $key and a $value as its parameters.

#Signature

The signature of the first method is:

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

#Example Use

The following code sample is an anonymous function assigned to a variable named $isPostFormat. The following example will use the Str::is helper method to check if a value is of the format /post/*:

1use Illuminate\Support\Str;
2
3$isPostFormat = function($key, $value) {
4    return Str::is('/post/*', $value);
5};

If a given value satisfies the format, true is returned, otherwise false is returned.

This would return true:

1$isPostFormat('key', '/post/array_first');

and this would return false:

1$isPostFormat('key', 'not-a-post');

So how does this work with the first function? Consider the following array:

1$sampleArray = [
2    'browser',
3    'headphones',
4    '/post/a-post-format',
5    'something else'
6];

We can call first function and pass our callback function as a parameter like so:

1<?php
2
3use Illuminate\Support\Arr;
4
5$firstPost = Arr::first(
6        $sampleArray,
7        $isPostFormat
8    );

The first function will iterate over every item in the array and apply our $callback function to each item. The first key/value pair to return true from the $callback function is returned as the value. Therefore, $firstPost would have the value of /post/a-post-format.

It is possible that no key/value pair will satisfy the callback function. To account for this, a $default value can be specified. The default value for the $default value is null. Consider the following array which has no valid post formats (according to our $isPostFormat function):

1$sampleArray = [
2    'browser',
3    'headphones',
4    'not-a-post-format',
5    'something else'
6];

the same code from earlier would return null instead of /post/a-post-format:

1use Illuminate\Support\Arr;
2
3$firstPost = Arr::first(
4    $sampleArray,
5    $isPostFormat
6);

The default value can be changed by passing a third argument to the first function:

1<?php
2
3use Illuminate\Support\Arr;
4
5$firstPost = Arr::first(
6    $sampleArray,
7    $isPostFormat,
8    '/post/this-is-my-default-value'
9);

The above code would return /post/this-is-my-default-value when no key/value pair satisfies the callback function.

#Optional $callback Parameter

The $callback function is an optional parameter, and can be omitted. When the $callback parameter is omitted, the first method will return the first item in the array:

1use Illuminate\Support\Arr;
2
3// 'browser'
4$firstItem = Arr::first(
5    $sampleArray
6);

#Global array_first Helper Function

The array_first function is a shortcut to calling Arr::first. This function is declared in the global namespace.

∎