array_find 怎样返回第一个匹配元素

PHP 的 array_find 会返回数组中第一个使回调条件成立的元素值，命中后不再检查后面的元素；没有匹配项时返回 null。需要原数组的键时使用 array_find_key。array_find 从 PHP 8.4.0 起提供，部署前要确认实际运行环境支持。

官方地址：https://www.php.net/

问题：只取一条符合条件的记录

假设服务端要从方案列表中选出一个已启用、席位数足够的方案。这里的目标是“取一条”，而不是先收集所有候选再取首项。我会优先用能直接表达该意图的写法，同时把列表顺序作为业务规则的一部分明确下来。

这是原创教学场景，代码没有在本文环境中执行，以下推导来自给定数据与函数约定。本文采用配方式组织，但示例是 PHP 服务端代码，不需要额外的前端框架、CSS 或浏览器特性。

最小配方：回调返回布尔条件

 ['name' => '基础版', 'enabled' => false, 'seats' => 8],
    'team' => ['name' => '协作版', 'enabled' => true, 'seats' => 16],
    'plus' => ['name' => '扩展版', 'enabled' => true, 'seats' => 32],
];

// 查找顺序以数组现有顺序为准，返回记录值而不是键
$chosen = array_find($plans, static function (array $plan, string $key): bool {
    return $plan['enabled'] === true && $plan['seats'] >= 12;
});

// 当前数据的记录值都是数组，因此可用严格的 null 判断未命中
if ($chosen === null) {
    echo '没有符合条件的方案';
} else {
    echo $chosen['name'];
}

按这组数据推导，协作版是先遇到的匹配记录。它不是“席位最多”的记录，也不是按键名字母排序得到的结果。若业务要求最便宜或优先级最高，先准备符合该规则的顺序，或者使用对应的比较逻辑，不能把“第一个”当成自动排序。

图中 plans、enabled、seats、callback、array_find、chosen 六个节点分别对应输入记录、条件和返回值。callback 依赖 enabled 与 seats；array_find 接收 plans 和 callback；chosen 绑定函数返回的记录值。连线只表达静态关联，没有模拟逐次执行。

值与键要分开处理

回调接收的参数顺序是 value 在前、key 在后。上例返回的是包含 name、enabled 和 seats 的数组值，原键 team 不会自动作为单独字段附到结果中。若后续必须保留键，可改用 array_find_key 获取键，再从源数组读取记录。

回调建议只判断，不夹带发送通知、扣库存等副作用。找到首项就会停止，因此不能依赖它对每条记录都做一次处理；副作用也会让简单的查找更难复查。

变体：匹配值允许为 null 时怎么办

array_find 的未命中值是 null，但数组中的某个合法元素也可能是 null。如果回调匹配到这个元素，单看返回值无法区分两种情况。下面以可空标签说明如何利用键保留命中信息。

 null, 'backup' => '备用标签'];

// 要区分“找到 null 值”和“完全没找到”，改为先查键
$foundKey = array_find_key(
    $labels,
    static fn ($value, $key): bool => $key === 'primary'
);
if ($foundKey !== null) {
    // 此处 $value 为 null，但 $foundKey 明确表示已经命中
    $value = $labels[$foundKey];
    echo '已找到指定标签键';
} else {
    echo '没有指定标签键';
}

图中 labels、primary、null值、array_find_key、foundKey、value 六个节点解释两个层次：labels 的 primary 元素可以具有 null值，array_find_key 的结果 foundKey 则用于定位 value。实际使用时应以 foundKey !== null 判断，不要使用简单的真假判断，因为合法键也可能是整数0或空字符串。

兼容旧版本的完整片段

若项目暂时不能使用原生函数，可以保留一个业务自己的 foreach 查找函数，不必冒用原生函数名。下面的结果同时包含 found、key 和 value，即使元素值是 null 也不会丢失命中信息。该片段使用箭头函数，面向支持这种语法的 PHP 环境。

 $value) {
        if ($matches($value, $key)) {
            return ['found' => true, 'key' => $key, 'value' => $value];
        }
    }
    return ['found' => false, 'key' => null, 'value' => null];
}

$stock = ['east' => 0, 'west' => 6, 'north' => 9];
// 使用与原生函数一致的值、键参数次序
$result = findFirstRecord($stock, static fn ($value, $key): bool => $value >= 5);
if ($result['found']) {
    echo $result['key'];
} else {
    echo '没有可用库存点';
}

与只返回 null 的通用辅助函数相比，我更倾向于在确实需要可空值的业务中返回显式 found 状态。它稍长一些，但调用方无需再猜测返回值代表什么。若数据约定从不包含 null，原生 array_find 的简洁接口通常已经足够。

几个容易误判的细节

空数组会返回什么？没有元素就没有匹配值，返回 null。业务可以统一展示未找到状态，而不是直接访问结果字段。

找到 false 或0时能写 if (!$chosen) 吗？不适合。false 和0都可能是合法的匹配元素，用真假判断会把它们与未找到混在一起。根据数据约定使用严格比较，或显式保留命中状态。

为什么换了数组顺序，结果也变了？第一个匹配项依赖数组现有顺序。如果顺序有业务含义，就在组装输入时保持它；如果需要排序，明确先排序再查找。

回调需要把参数写成引用吗？查找条件通常无需修改原数据。保持纯判断更清楚，也避免把修改记录与选择记录两项责任混在一起。

我的选择标准是先看下游需要值、键还是显式命中状态，再选函数。把这三项分清，最小查找写法才不会在可空值或合法假值处留下歧义。

函数文档：https://www.php.net/manual/en/function.array-find.php

键查找文档：https://www.php.net/manual/en/function.array-find-key.php