array_find
Returns the value of the first array element for which a callback returns true, or null if none match.
array_find(array $array, callable $callback): mixed- Added in PHP 8.4
Parameters
| Parameter | Type | Description |
|---|---|---|
$array | array | The array that should be searched. |
$callback | callable | Called as callback(mixed $value, mixed $key): bool for each element. If it returns true, that element's value is returned and the callback is not called for further elements. |
Return value
mixedThe value of the first element for which callback returns true, or null if no element matches.
Errors
Throws a TypeError if $callback is not callable, and an ArgumentCountError if the callback declares more than two required parameters.
The pre-8.4 idiom was $m = array_filter($arr, $fn); $first = $m ? reset($m) : null; or array_values(array_filter(...))[0] ?? null. reset() cannot be written directly around the array_filter() call, because it takes its argument by reference and passing a function's return value emits "Only variables should be passed by reference" — the same restriction this site's array_first page describes.
Example
When to use it
- Pull the first address flagged as the default out of a user's address list.
- Find the first validation rule that a submitted value fails, to report its message.
- Look up a currency row by ISO code in a decoded JSON payload.
Frequently asked questions
What is the difference between array_find and array_search?
array_search() looks for a value equal to the needle and returns its key, while array_find() runs a callback and returns the matching value. Use array_search() for plain equality and array_find() when the match is a condition.
Does array_find return the key or the value?
The value. Use array_find_key() if you need the key of the first matching element.
How can I tell 'no match' from a matched null?
Use array_find_key() and test the result with !== null. array_find() returns null in both cases and cannot distinguish them.
More examples
Compared with the array_filter workaround
array_find() returns float(14) straight away. array_filter() instead returns both matching entries with their keys ('l' and 'xl') and needs reset() to reduce that to a single value.
<?php
$prices = ['s' => 4.5, 'm' => 9.0, 'l' => 14.0, 'xl' => 21.0];
var_dump(array_find($prices, fn(float $p) => $p > 10));
// The pre-8.4 equivalent
$matches = array_filter($prices, fn(float $p) => $p > 10);
print_r($matches);
var_dump(reset($matches) ?: null);Using the key inside the callback
The first call prints string(3) "cow", because 'c' => 'cow' is the first pair where the value begins with its key. The second prints string(4) "duck", the first name over three letters long.
<?php
$animals = ['a' => 'dog', 'b' => 'cat', 'c' => 'cow', 'd' => 'duck'];
// First entry whose value starts with its own key.
var_dump(array_find($animals, fn(string $v, string $k) => $v[0] === $k));
// First name longer than three characters.
var_dump(array_find($animals, fn(string $v) => strlen($v) > 3));
Discussion