PHP 8.5 array_first 怎样取得首个元素

如果你在 PHP 8.5 中只想拿到数组的第一个值，直接使用 array_first($array)。它按数组当前的迭代顺序读取首值，不要求第一个键必须是 0；数组为空时返回 null。需要注意的是，非空数组的首值也可能本来就是 null，所以业务代码不能只用返回值判断数组是否为空。

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

迁移到 PHP 8.5 时，把“读首值”“读首键”和“兼容旧版本”分成三个决策：只要值就用 array_first()，需要键就用 array_key_first()，仍需支持旧版本时保留一个明确的回退函数。

array_first 的返回值到底按什么顺序确定

PHP 数组是有序映射。这里的“首个”指当前数组遍历时遇到的第一个元素，而不是数值最小的键，也不是强行读取 $array[0]。因此，即使数组的键是 10、3、8，array_first() 仍然会返回最先插入的那个元素的值。

用 array_first 读取非连续键数组

下面这个例子故意使用非连续键，模拟接口结果经过筛选后留下的记录。示例只关注首值读取，不把键名当成业务排序条件。

 ['id' => 12, 'name' => 'alpha'],
    4  => ['id' => 4, 'name' => 'beta'],
];

// array_first 按当前数组顺序取值，不要求首键是 0。
$firstRecord = array_first($records);

// 先判断是否真的取到记录，再使用记录字段。
if ($firstRecord !== null) {
    echo $firstRecord['name'];
}
?>

这个写法的重点是“取值目标明确”。如果业务的首条记录必须按时间、优先级或数据库排序确定，应先在数据源层完成排序；array_first() 只读取传入数组已经呈现出来的顺序，不会替你重新排序。

空数组和首值为 null 要分开处理

官方手册规定：非空数组返回第一个值，空数组返回 null。但“非空数组的第一个值就是 null”也完全可能发生，所以以下两种输入会得到相同的返回值：

 null];

// 两个结果都可能是 null，不能只靠返回值判断数组状态。
$emptyValue = array_first($empty);
$nullValue = array_first($hasNull);

// 需要区分“没有元素”和“首元素值为 null”时，先看数组是否为空。
if ($empty === []) {
    echo '没有首元素';
} elseif ($nullValue === null) {
    echo '有首元素，但它的值是 null';
}
?>

在更复杂的代码里，可以把“是否存在首元素”和“首元素的值”封装成两个字段，或者沿用项目已有的结果对象。不要为了消除一个 null 而把所有值转成字符串，这会改变类型语义。

array_first、array_key_first 与兼容写法怎样选择

三个写法解决的是不同问题。array_first() 返回值；array_key_first() 返回首键；如果项目还运行在没有 array_first() 的 PHP 版本上，就需要在自己的兼容层提供回退。把这三个需求混成“取第一个元素”容易在迁移后留下隐蔽的类型错误。

 'draft', 9 => 'published'];

// 只需要首值：PHP 8.5 直接调用 array_first。
$firstValue = array_first($items);

// 需要首键：用 array_key_first，再按键读取对应值。
$firstKey = array_key_first($items);
$valueByKey = $firstKey === null ? null : $items[$firstKey];

// 旧版本兼容层：foreach 取得首值，不改变原数组指针。
function first_value_compat(array $items): mixed
{
    foreach ($items as $value) {
        // 第一次迭代就是当前数组顺序中的首值。
        return $value;
    }

    // 空数组没有首值，保持与 array_first 相同的 null 语义。
    return null;
}
?>

如果只支持 PHP 8.5 及以上，优先使用内置函数，代码意图最清晰；如果还要跨版本发布，把兼容函数集中在一个小文件中，并用 function_exists('array_first') 作为切换条件。兼容层不要散落在每个业务调用点。

把 array_first 放进实际接口读取场景

以“接口返回候选记录，业务只展示第一条”为例，推荐先把输入规范化，再读取首值。这样空数组、首值为 null 和正常记录都有明确落点，后续也更容易补测试。

这个函数的返回类型表达了一个业务约束：调用方只接受“首条记录是数组”或“没有可用记录”。如果你的接口允许首条记录为标量，应该调整返回类型，而不是在函数内部悄悄丢弃它。

PHP 8.5 升级前后的落地清单

PHP 官方迁移指南提醒，小版本升级也应在切换生产版本前完成测试。针对 array_first()，可以把检查项压缩成下面六条：

• 确认运行环境确实是 PHP 8.5 或更高版本，再直接调用 array_first()。
• 确认“首个”代表输入数组当前顺序，而不是最小键或某个业务排序。
• 用非连续键测试一次，避免把 $array[0] 当成通用首值写法。
• 分别覆盖空数组和首值为 null 的输入。
• 需要首键时改用 array_key_first()，不要从首值反推键。
• 旧版本项目集中维护回退函数，并为回退函数保留同样的边界测试。

常见问题

array_first() 会返回键最小的元素吗？

不会。它读取数组当前顺序中的第一个值；如果业务要按键或时间排序，应先明确排序规则。

空数组调用 array_first() 会抛异常吗？

官方手册说明空数组返回 null。调用方仍应根据业务区分“没有元素”和“首元素值为 null”。

我只想拿第一个键，应该用什么？

使用 array_key_first()。它返回首键，再由调用方决定是否用该键读取值。

PHP 8.4 项目能直接使用 array_first() 吗？

不能把 PHP 8.5 的内置函数假设成旧版本能力。跨版本项目应使用集中式兼容函数，或在升级运行时后再切换到内置函数。

最终可以这样记：array_first() 负责“首值”，按输入数组当前顺序读取；空数组返回 null；需要首键或兼容旧版本时，选择对应的专用写法。把这三个边界写进测试，迁移 PHP 8.5 时就不容易把键、值和空结果混在一起。