PHP 怎样在数组中返回首个满足条件的值

在订单、配置或权限数组里，我们经常只想拿到“第一个满足条件的值”，而不是把所有结果筛出来。PHP 8.4 提供的 array_find() 正好解决这个问题：回调返回 true 时立即返回当前元素值，后面的元素不会继续调用回调；找不到匹配项时返回 null。

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

这篇只围绕三个边界展开：回调如何接收值和键、为什么只返回首个匹配，以及返回值为 null 时怎样避免误判。

先准备一个要查找的 PHP 数组

假设系统收到一组按优先级排列的支付渠道，我们想找到第一个处于启用状态、并且支持当前币种的渠道。数组的顺序很重要，因为“首个”就是按数组遍历顺序决定的。

 '银行卡', 'enabled' => false, 'currency' => 'CNY'],
    ['name' => '钱包', 'enabled' => true, 'currency' => 'USD'],
    ['name' => '快捷支付', 'enabled' => true, 'currency' => 'CNY'],
];

$currency = 'CNY';
?>

这里的目标是返回完整的渠道数组，而不是只返回 name 字段。这样后续代码仍能读取渠道的其他配置。

用 array_find 返回首个匹配值

array_find(array, callback) 的回调签名是 callback(mixed $value, mixed $key): bool。回调返回真值时，函数返回当前的 $value；因此下面的结果是“快捷支付”这条完整数组记录。

当回调检查到第三个元素返回 true 后，array_find() 就结束搜索。它不会像 array_filter() 那样构造一个包含全部命中项的新数组，也不会继续检查后面的元素。

需要键时，回调的第二个参数就是 key

回调可以接收两个参数：第一个是当前元素值，第二个是当前键。参数顺序固定为 value, key，不能写成常见的 key, value。当数组键携带租户、区域或配置版本信息时，可以把键也放入条件。

 ['enabled' => false],
    'us-primary' => ['enabled' => true],
    'cn-backup' => ['enabled' => true],
];

// 只在键以 cn- 开头且记录启用时命中。
$rule = array_find(
    $rules,
    function (array $value, string $key): bool {
        return str_starts_with($key, 'cn-') && $value['enabled'];
    }
);

var_dump($rule);
// array(1) { ["enabled"]=> bool(true) }
?>

这个例子返回的是 cn-backup 对应的值，但不会返回它的键。如果业务需要键本身，PHP 8.4 还提供了对应的 array_find_key()。

null 未命中时，怎样避免把结果解释错

没有元素满足条件时，array_find() 返回 null。如果数组中的合法元素本身也可能是 null，仅凭返回值就无法区分“命中了一个 null”还是“没有命中”。这时应改用 array_find_key()，因为数组键不会是 null。

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

// 用键判断是否命中，避免把合法的 null 当成搜索失败。
$key = array_find_key(
    $values,
    function (?string $value): bool {
        return $value === null;
    }
);

if ($key !== null) {
    // 这里能确认确实命中了 first，而不是没有结果。
    var_dump($values[$key]);
}
?>

PHP 8.4 以下版本用 foreach 保持同样语义

array_find() 是 PHP 8.4 新增的数组函数。如果项目仍运行在更早版本，可以用一个小型 foreach 辅助函数复现“命中即返回、遍历结束返回 null”的语义。

 $array
 * @param callable $callback 回调参数顺序为 value、key
 */
function first_value(array $array, callable $callback): mixed
{
    foreach ($array as $key => $value) {
        // 命中后立即返回，避免继续执行后续回调。
        if ($callback($value, $key)) {
            return $value;
        }
    }

    // 没有命中时与 array_find 保持相同的返回约定。
    return null;
}
?>

兼容函数的重点不是名字完全一致，而是保留三个行为：按原数组顺序查找、回调返回真值就停止、没有匹配时返回 null。如果值允许为 null，旧版本也应提供一个返回键的变体，或把“是否命中”作为额外状态返回。

array_find、array_find_key 和 array_filter 怎么选

如果只需要第一个结果，优先用 array_find() 表达意图；如果需要全部结果才使用 array_filter()。另外，array_filter() 保留原键，返回的数字键可能出现间隔；这和“拿到一个首个值”的需求并不相同。

常见问题

array_find() 会返回数组的键吗？

不会，它返回首个匹配元素的值。需要键时使用 array_find_key()，再通过键访问原数组。

回调返回整数 1 可以吗？

可以，PHP 会按布尔语义判断回调结果；为了让代码意图更清楚，建议把回调声明为返回 bool，并显式返回条件表达式。

为什么不用 array_filter()[0]？

这种写法会先遍历并构造全部过滤结果，还可能遇到非连续键，不能稳定表达“第一个匹配值”。array_find() 直接表达首个匹配，并在命中后停止。

实际使用时先确认运行环境是否为 PHP 8.4 或更高版本，再根据业务要返回值、键还是全部结果选择函数。特别是合法值可能为 null 时，不要把单个 null 结果直接当作未命中。