array_find()

Purpose

array_find() searches an array from the beginning and returns the value of the first element for which your callback says "yes". It stops as soon as a match is found, so later elements are never passed to the callback. It is available from PHP 8.4.0.

Use it when you need one item, such as the first overdue invoice, the first product in stock or the first string with a given prefix. If you need every matching item, use array_filter() instead.

Signature

Parameters and defaults

• $array: the array to search. Both list arrays and arrays with string keys are accepted. The search follows the array's current iteration order.
• $callback: a callable invoked as callback(mixed $value, mixed $key): bool. It receives the element value first and the key second. A callback may declare only the first parameter if the key is not needed.

Neither parameter has a default value, so both are required.

Return value and failure cases

The function returns the value of the first element for which the callback returns true. If no element matches, or the array is empty, it returns null. A non-match is not an error and does not raise a warning.

Passing something that is not an array or not callable is a usage error and results in a TypeError, as with other typed built-in functions.

Example 1: first value that satisfies a condition

The callback is a short arrow function. The numbers 4, 8 and 15 fail the test, so the search ends at 16.

<?php
$numbers = [4, 8, 15, 16, 23, 42];
$found = array_find($numbers, fn(int $n): bool => $n > 15);
echo json_encode($found), "\n";

16

The result is the value 16, not its position.

Example 2: using keys and handling no match

The second callback parameter is the array key. Here the callback combines a value check and a key check. A second search that cannot succeed returns null.

<?php
$stock = ['apple' => 0, 'pear' => 5, 'plum' => 9];
$inStock = array_find($stock, fn(int $qty, string $name): bool => $qty > 0 && $name !== 'apple');
$none = array_find($stock, fn(int $qty): bool => $qty > 100);
echo json_encode(['inStock' => $inStock, 'none' => $none]), "\n";

{"inStock":5,"none":null}

Notice that pear is returned as its quantity, 5, rather than as the pair pear => 5. The key is available to the callback but is not part of the return value.

Example 3: the null ambiguity

Because "not found" is reported as null, an array that contains null can produce a result that looks like a failed search. When the key matters or null is a valid element, pair the call with array_find_key().

<?php
$values = [1, null, 3];
$result = array_find($values, fn($v) => $v === null);
$key = array_find_key($values, fn($v) => $v === null);
echo json_encode(['value' => $result, 'key' => $key]), "\n";

{"value":null,"key":1}

The value is null even though a match did exist. The key, 1, proves the search succeeded.

Edge cases

• Empty array: the callback is never called and the result is null.
• Several matches: only the first one in iteration order is returned.
• Falsy matches: values such as 0, '' or false can be returned if the callback accepts them. Check the result with === null rather than a truthiness test like if ($result).
• Short-circuiting: once the callback returns true, no more elements are visited. Side effects inside the callback therefore happen only up to the first match.
• Objects and nested arrays: the returned value is whatever element was stored, so a matching record array or object is returned in full.

Common mistakes

1. Expecting a key. array_find() returns the value. Use array_find_key() when you need the key.
2. Treating null as always meaning missing. If null can be stored in the array, the return value alone cannot distinguish the two cases.
3. Testing the result loosely. Writing if (array_find(...)) fails for matching elements like 0 or an empty string.
4. Swapping callback parameters. The value comes first and the key second, the opposite of what some developers expect from foreach ($array as $key => $value).
5. Writing callbacks that do too much. Keep the callback as a pure yes/no test, so the search is easy to reason about.

Related functions

• array_find_key() returns the key of the first matching element.
• array_any() checks whether at least one element satisfies a callback.
• array_all() checks whether every element satisfies a callback.
• array_filter() returns all matching elements, not just the first.
• array_reduce() folds an array into a single value using a callback.

Recap

array_find() takes an array and a callback, returns the first value whose callback result is true, and returns null when nothing matches. The callback receives the value and the key. Remember that the function stops early, that the key is not returned, and that a stored null can be confused with a missing result unless you also consult array_find_key().