PHP array_key_first 怎样安全处理空数组

我在把一段旧 PHP 数组代码迁移到新版本时，最容易忽略的不是函数名，而是“没有首键”这件事。array_key_first() 在非空数组中返回第一个键，在空数组中返回 null，而且不会改变数组的内部指针。安全写法是先把返回值当作可空键处理，再决定是否继续读取。

官方说明：https://www.php.net/manual/en/function.array-key-first.php

结论：不要用 if ($key) 判断首键是否存在，因为合法的整数键 0 会被误判；使用 $key === null 或先用 isset($items[0]) 之类的业务条件明确区分。

升级范围：array_key_first 解决了哪一类旧代码问题

官方文档标注该函数从 PHP 7.3.0 开始提供。更早的代码常见两种替代：array_keys($items)[0] ?? null 会先构造全部键，reset($items); key($items) 则可能改变内部指针。迁移时应先确认运行环境，再选择能表达业务边界的写法。

先分清空数组、整数键和键值为 null

首键是键，不是首个值。数组可以有整数键 0，也可以有字符串键；首个元素的值即使是 null，也不影响首键的判断。因此，下面代码把“没有首键”和“首元素值为空”拆成两个变量，避免把不同语义压成一个真假值。

 false, 'key' => null, 'value' => null];
    }

    // 首键与首值分开读取；首值本身可以合法地是 null。
    return [
        'has_key' => true,
        'key' => $firstKey,
        'value' => $items[$firstKey],
    ];
}

$result = readFirstEntry([0 => null, 'next' => 'ready']);
// 这里只展示数据契约，不把 null 值当作“没有首项”。
var_dump($result);

这段代码的关键是 $firstKey === null。不要改成 if (!$firstKey)，因为键为 0 时会被错误地当作不存在。也不要用 isset($items[$firstKey]) 代替首键判断：当首值恰好为 null 时，isset 会返回 false。

迁移旧写法时，优先保留“无指针副作用”

如果项目最低版本已经是 PHP 7.3，直接替换为 array_key_first 最清楚。若仍需支持更早版本，可以使用官方文档给出的 foreach polyfill：第一次循环立即返回键，空数组循环不进入并返回 null。它不需要先生成完整键列表，也不会修改内部指针。

 $_unused) {
            return $key;
        }
        return null;
    }
}

// 迁移后仍按可空返回值处理，避免把兼容层当成必有元素。
$firstKey = array_key_first($items ?? []);
if ($firstKey !== null) {
    echo '首键：' . (string) $firstKey;
}

回归检查：四个边界足够覆盖这次改动

迁移后我会把检查项固定成四组：空数组返回 null；整数键为 0 时仍被识别；字符串键能够原样返回；首个值为 null 时仍判定“有首键”。如果业务依赖同一个数组后续继续 current()、next() 遍历，还要确认迁移前后的内部指针语义没有被旧的 reset() 破坏。

最后再看最低 PHP 版本：能统一升级到 7.3 以上就删除临时兼容代码；无法统一升级时保留命名清晰、返回类型一致的 polyfill，并把它放在公共兼容层，而不是散落在业务函数里。这样以后移除兼容层时，只需要检查一个入口。

相关问题

array_key_first 返回的是值吗？不是，它返回首键；要取值需再用该键访问数组。

首键可以是 null 吗？数组键只能是整数或字符串，所以 null 在这里表示空数组没有首键，而不是一个有效数组键。

为什么不总是用 array_keys？它可以工作，但会先构造完整键列表；只需要首键时，array_key_first 更直接，也避免移动内部指针。