PHP array_is_list 怎么识别连续数字索引

处理 JSON 入参或批量参数时，PHP 数组“看起来像列表”并不等于它真的具备列表结构。判断关键不在值是不是字符串或数字，而在键是否严格从 0 开始连续递增。PHP 8.1 起可以直接调用 array_is_list()；空数组返回 true，键缺号、乱序或混入字符串键则返回 false。

官方文档：https://www.php.net/manual/en/function.array-is-list.php

一、先把“连续数字索引”说准确

PHP 的普通数组既能当列表，也能当字典。下面四组数据的值都很普通，但键结构完全不同：['red', 'blue'] 的键是 0、1；[1 => 'red', 2 => 'blue'] 从 1 开始；[0 => 'red', 2 => 'blue'] 中间缺少 1；[0 => 'red', 'name' => 'blue'] 混入了字符串键。只有第一组满足 list 的定义。

可以把判断规则记成：对长度为 n 的数组，键集合必须正好是 0, 1, 2, ..., n-1，并且迭代顺序与这个序列一致。值可以重复，也可以是数组或对象；值本身不会让结果变成 false。

二、用 array_is_list 覆盖常见输入

把判断集中在一个小表格里，比只记住“索引数组返回 true”更可靠：

下面的示例刻意把边界放在同一个数组中，便于接口测试直接复用。代码只输出判断结果，不把输出当成运行截图；它表达的是函数契约：

 [],
    'normal' => ['red', 'blue', 'green'],
    'starts-at-one' => [1 => 'red', 2 => 'blue'],
    'has-gap' => [0 => 'red', 2 => 'green'],
    'mixed-key' => [0 => 'red', 'name' => 'blue'],
];

foreach ($samples as $label => $value) {
    // array_is_list 只判断键是否连续，不会检查值的业务含义。
    printf("%s: %s\n", $label, array_is_list($value) ? 'list' : 'map');
}
?>

实际调用时不要用 array_keys($value) === range(...) 代替它作为默认写法：那种表达式会额外创建键数组，并且空数组、类型比较和边界处理都需要调用方自己维护。PHP 8.1 以上直接使用内置函数，意图更清楚。

三、需要列表语义时先重建键

array_is_list() 只负责回答“现在是不是列表”，不会替你修复数组。如果业务允许丢弃原键，可以用 array_values() 生成新的 0 起始序列；如果原键有业务含义，则应该保留关联数组，不要为了让检查通过而重建。

 'red', 2 => 'green'];

if (!array_is_list($filtered)) {
    // 这里明确表示放弃原键，只保留顺序和值。
    $list = array_values($filtered);
} else {
    $list = $filtered;
}

var_dump($list); // 结果结构为 ['red', 'green']，新键是 0、1。
?>

这一步常见于 array_filter() 之后：过滤函数会保留原键，所以结果可能仍然是稀疏数组。若数据要进入只接受列表的 JSON 契约，重建键应当是显式决策，而不是隐藏在通用工具函数里。

四、兼容 PHP 8.1 以下的运行环境

官方函数从 PHP 8.1 开始提供。如果项目还要支持更早版本，可以用一次遍历的兼容函数，但要把它放在兼容层，并保持与内置函数同样的空数组语义：

 $_value) {
        // 严格比较可区分整数键和看似相同的字符串键。
        if ($key !== $expected) {
            return false;
        }
        $expected++;
    }
    return true;
}
?>

新项目不必重复维护这段兼容逻辑；只有最低 PHP 版本确实低于 8.1 时才保留。无论使用哪个实现，都要在接口边界写清楚“空列表是否允许、关联对象是否允许、过滤后是否自动重建”，这样调用方得到的是稳定的数据契约。

相关问题

值是数字数组，为什么仍可能返回 false？

函数看的是键，不是值。只要键从 1 开始、存在缺口、顺序错乱或混入字符串键，就不符合 list 定义。

空数组算不算列表？

算。空数组没有违反“从 0 到 count-1 连续”的条件，因此 array_is_list([]) 返回 true。

array_values 会不会改变原数组？

不会。它返回一个重新编号的新数组；是否用新数组替换原变量，应由业务是否依赖原键来决定。