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.
∎