PHP array_find 怎么返回首个匹配值

在 PHP 8.4 及更高版本里，array_find() 会按数组原有顺序调用回调，并返回第一个让回调返回 true 的元素值。没有匹配项时结果是 null。因此它适合“找到第一个符合条件的记录并继续处理”的场景，不适合需要一次拿到全部匹配项的筛选任务。

官方参考：https://www.php.net/manual/en/function.array-find.php

最小写法是 array_find($array, fn ($value, $key) => 条件)。函数返回值，不返回键；如果数组里允许出现 null，要用 array_find_key() 额外确认是否真的命中。

先确认 array_find 的输入和返回边界

array_find(array $array, callable $callback): mixed 接收数组和回调两个参数。回调的第一个参数是当前值，第二个参数是当前键；当回调首次返回 true 时，函数立即返回这个值，后面的元素不会再调用回调。这个“只取首个结果”的语义，正是它和 array_filter() 的区别。

用值回调返回第一个匹配元素

例如从订单数组中找到第一个状态为 paid 的订单。回调只关心值时可以省略键参数，但要保留值类型和返回布尔值的约束。

 101, 'status' => 'pending'],
    ['id' => 102, 'status' => 'paid'],
    ['id' => 103, 'status' => 'paid'],
];

// 回调返回 true 后 array_find 会停止继续查找，结果是首个已支付订单。
$firstPaid = array_find($orders, function (array $order): bool {
    return $order['status'] === 'paid';
});

// 这里拿到的是订单值，不是键；未命中时需要按 null 边界处理。
var_dump($firstPaid['id'] ?? null); // 102
?>

即使第三条也满足条件，结果仍然是 id 为 102 的订单。若目标是收集所有已支付订单，应改用 array_filter()；若目标是只知道有没有匹配项，可以考虑 array_any()。

把键和值一起放进匹配条件

当数组键本身包含业务编号时，回调可以声明第二个参数。参数顺序固定为“值、键”，不能写成“键、值”。下面只寻找键为 vip 且值已启用的配置。

 ['enabled' => true],
    'vip' => ['enabled' => true],
    'admin' => ['enabled' => true],
];

// 同时检查 value 和 key，避免只按值命中错误配置。
$vipFeature = array_find($features, function (array $feature, string $key): bool {
    return $key === 'vip' && $feature['enabled'] === true;
});

var_dump($vipFeature); // ['enabled' => true]
?>

null 结果要用 array_find_key 消除歧义

array_find() 未命中返回 null，但数组中也可能存在一个实际值就是 null。这时单看返回值无法区分“命中了 null”和“根本没有命中”。官方提供的 array_find_key() 返回首个匹配键；因为数组键不能是 null，它更适合做存在性判断。

 null, 'ready' => 'ok'];

// 这里只返回值，null 可能来自命中的 empty，也可能来自搜索失败。
$value = array_find($values, fn (mixed $value): bool => $value === null);

// 用键判断是否存在匹配项，再回表取值，结果就不会混淆。
$key = array_find_key($values, fn (mixed $value): bool => $value === null);
if ($key !== null) {
    $value = $values[$key];
}
?>

PHP 8.3 及更早版本的兼容写法

如果项目还没有升级到 PHP 8.4，可以用条件定义保留相同语义。不要无条件声明同名函数，否则升级运行环境后会和内置函数冲突。

 $value) {
            // 同时传入 value 和 key，保持 PHP 8.4 的回调约定。
            if ($callback($value, $key)) {
                return $value;
            }
        }

        // 没有匹配项时与 array_find 保持一致。
        return null;
    }
}
?>

实际项目里可通过版本约束决定使用内置函数还是兼容函数。最后记住三点：只取一个值用 array_find()，要键用 array_find_key()，要全部结果用 array_filter()。若匹配值允许为 null，先拿键再取值。

常见问题

array_find 会返回数组键吗？

不会，它返回首个匹配元素的值。需要键时应使用 array_find_key()。

没有匹配项时可以用 false 判断吗？

不建议。未命中约定返回的是 null，而数组值也可能是 false 或 0；需要可靠判断时应使用严格的 null 边界，或先取得匹配键。