PHP SplFixedArray 什么时候值得用：索引边界、内存取舍与 JSON 转换

批量导入任务有一个很明确的上限：一次只接收 5000 条记录。团队如果继续用普通 PHP 数组，代码可以工作，但容量、越界和“中间位置是否存在”都靠约定维持。SplFixedArray 把这个边界写进容器本身，适合索引数量确定、需要控制误写的场景；它不是把所有数组替换掉就能自动提速的魔法开关。

问题现场：5000 个位置为什么值得固定下来

下面的导入器接收批次编号和固定大小的行缓冲。普通数组会随着写入自动增长，拼写错误的索引也可能在很远的位置留下一个新元素：

$rows = [];
$rows[0] = ['id' => 1001];
$rows[5000] = ['id' => 6001]; // 普通数组会接受这个键

var_dump(count($rows)); // 2，但最大键已经是 5000

count() 只告诉你有多少个元素，不告诉你索引是否落在这一批的边界里。如果业务把数组当作“第 N 个槽位”，普通数组的键语义很容易被误用。

先建立容器：容量是结构的一部分

$buffer = new SplFixedArray(3);
$buffer[0] = ['id' => 1001];
$buffer[1] = ['id' => 1002];

echo $buffer->count(); // 3
var_dump($buffer[2]);   // NULL，槽位存在但尚未写入

创建容量为 3 的容器后，count() 返回的是容量，不是已写入元素数量。第三个槽位已经存在，只是值为 null。如果导入记录允许数据库字段本身为 null，就不能仅凭读取结果判断“空槽”还是“真实空值”，应额外维护写入计数或状态。

SplFixedArray 的索引从 0 开始，不能像普通数组那样随意使用字符串键。这个限制正是它适合固定位置缓冲的原因，也是它不适合键值映射的原因。

动手验证：越界和扩容都必须显式发生

$buffer = new SplFixedArray(2);
$buffer[0] = 'ready';

try {
    $buffer[2] = 'too far';
} catch (RuntimeException $e) {
    echo $e->getMessage();
}

$buffer->setSize(3);
$buffer[2] = 'now valid';

越界写入不会悄悄把容量变成 3。需要增加容量时调用 setSize()，缩小时还要确认被截断的位置没有未处理数据。把容量变化放进批次状态机，而不是让业务代码在任意地方随手扩容，排查问题会容易很多。

定位取舍：固定容量不等于所有场景更省

固定数组的主要价值是把“有多少个位置”变成可检查的结构约束。不要只看到类名里有 Fixed 就承诺它一定比普通数组省内存或更快；真实收益取决于元素数量、访问方式、PHP 版本和后续转换成本。

如果代码需要按用户 ID、SKU 或字段名查找，使用普通关联数组更自然。如果代码要频繁追加、删除和重新编号，普通数组或专门的队列结构通常更清晰。SplFixedArray 更适合“容量已知、位置有意义、越界应尽早暴露”的缓冲区。

接口边界：转 JSON 前先还原成普通数组

$buffer = new SplFixedArray(2);
$buffer[0] = ['id' => 1001];
$buffer[1] = ['id' => 1002];

$payload = [
    'items' => iterator_to_array($buffer),
];

echo json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR);

在接口层显式调用 iterator_to_array()，可以把容器转换步骤写出来，也能在这里决定是否保留键。固定数组的索引是连续的，常见的结果会编码成 JSON 数组；但如果中间存在业务上的空槽，接口仍应先明确“空槽是否应该过滤”，再决定输出契约。

不要把 SplFixedArray 直接塞进多个序列化层，尤其不要依赖某个框架对 SPL 对象的默认处理。边界处转换成普通数组或明确的 DTO，调试输出和接口文档都会更稳定。

验收清单：把容量、写入数和输出形状分开测

$buffer = new SplFixedArray(3);
$written = 0;

foreach ([1001, 1002] as $id) {
    if ($written >= $buffer->count()) {
        throw new OverflowException('batch buffer is full');
    }
    $buffer[$written++] = ['id' => $id];
}

$items = array_slice(iterator_to_array($buffer), 0, $written);
assert(count($items) === 2);
assert($items[0]['id'] === 1001);
assert(json_encode($items, JSON_THROW_ON_ERROR)[0] === '[');

这个小测试把三个概念拆开了：容器容量是 3，实际写入数是 2，对外返回的列表长度也是 2。生产代码还应覆盖满容量、零条数据、扩容前越界和缩容截断等情况。

常见问题

SplFixedArray 能不能像普通数组一样使用 [] 追加？

不应依赖自动追加。它的容量和索引是显式边界，追加前应计算目标索引并确认没有越界。

未写入的槽位为什么是 null？

容器先分配了位置，但没有给该位置设置业务值，因此读取结果是 null。这不等于数据库中的真实空值。

SplFixedArray 一定比普通数组省内存吗？

不能脱离数据规模和运行环境下结论。应使用项目自己的批量大小、元素结构和 PHP 版本做基准测试。

接口需要返回 SplFixedArray 对象吗？

不需要。接口边界建议转成普通数组或 DTO，再由统一序列化层输出 JSON，避免把容器实现细节暴露给调用方。

收束：把固定边界用在真正需要的位置

SplFixedArray 解决的是“位置和容量必须可控”，不是“普通数组性能不够”的统一答案。先确认批次大小已知、整数索引有业务意义，再用越界失败和显式扩容建立检查点；到了接口边界，把容器转换成普通数组并验收输出形状，这样固定容量的约束才不会变成新的隐性复杂度。