array_find_key
Returns the key of the first array element for which a callback returns true, or null if none match.
array_find_key(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 key is returned and the callback is not called for further elements. |
Return value
mixedThe key 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.
array_find_key() is the key-returning sibling of array_find(). It walks the array in order, and the first time the callback returns truthy it returns that element's key and stops.
Two situations call for it specifically. First, when you need to modify the element in place: get the key, then write to $array[$key] or call unset() or array_splice() on it. Second, when the array may contain null values — the key tells you unambiguously whether a match happened, which array_find() cannot.
Compared with array_search
array_search() does the same job for a plain value comparison and is faster for that case. array_find_key() is what you want when the match depends on a computed condition, a nested field, or the key itself.
Watch out for falsy keys
On a list, the key of the first element is 0. Writing if ($key = array_find_key(...)) silently treats that as "not found". Always compare with !== null, exactly as you would with array_search() and its false return.
Example
When to use it
- Find the index of a cart line by product id so you can update its quantity in place.
- Locate the position of the first log entry above a severity threshold before slicing the tail.
- Detect which config key holds a null value so you can report exactly what is missing.
Frequently asked questions
What is the difference between array_find and array_find_key?
array_find() returns the matching element's value; array_find_key() returns its key. Use the key version when you need to modify or remove the element, or when the array can contain null values.
What does array_find_key return when nothing matches?
null. That differs from array_search(), which returns false, so do not copy a === false check across from older code.
Is array_find_key faster than array_search?
No. array_search() is a native value comparison with no per-element callback, so it wins on plain equality. array_find_key() is for conditions that array_search() cannot express.
More examples
Update a list element in place
The key 1 is returned, so the second line's quantity becomes 6. Note the !== null test: had B-2 been the first line the key would be 0, and a plain if ($i) would have skipped the update.
<?php
$cart = [
['sku' => 'A-1', 'qty' => 1],
['sku' => 'B-2', 'qty' => 4],
];
$i = array_find_key($cart, fn(array $line) => $line['sku'] === 'B-2');
if ($i !== null) {
$cart[$i]['qty'] += 2;
}
print_r($cart);Falsy keys are the classic bug
The key is int(0), a genuine match. The truthiness test wrongly reports "not found", while the !== null test reports "found".
<?php
$names = ['ana', 'bo', 'cy'];
$key = array_find_key($names, fn(string $n) => $n === 'ana');
var_dump($key);
// Wrong: 0 is falsy
var_dump($key ? 'found' : 'not found');
// Right
var_dump($key !== null ? 'found' : 'not found');
Discussion