Laravel 资源类的 mergeWhen() 方法要求数组键必须统一类型且数字键需连续有序，否则可能因 PHP 数组底层行为导致键冲突、值被意外覆盖或顺序错乱，引发不可预测的数据丢失。
laravel 资源类的 `mergewhen()` 方法要求数组键必须统一类型且数字键需连续有序，否则可能因 php 数组底层行为导致键冲突、值被意外覆盖或顺序错乱，引发不可预测的数据丢失。
在 Laravel 资源（如 JsonResource 或 ResourceCollection）中，mergeWhen() 是一个便捷的条件合并工具，用于根据布尔表达式动态注入字段。其底层依赖 PHP 原生的 array_merge() 行为，而该函数对混合键类型数组的处理具有隐式且易出错的规则——这正是官方文档明确警告的核心原因。
? 为什么不能混用字符串与数字键？
PHP 数组本质上是有序哈希表，但其键解析存在两类关键机制：
-
数字键自动转换与重排
若使用类似 '1'、'08'、1.5 等“看似数字”的字符串键，PHP 会尝试将其转为整型（如 '1' → 1，'08' → 8），而 '08'（带前导零）因不符合标准整数表示，保留为字符串键；但 '1' 和 1 在 array_merge() 中会被视为同一键，导致后写入值覆盖前者：$arr = ['1' => 'string-key', 1 => 'int-key']; print_r(array_merge($arr, ['foo' => 'bar'])); // 输出: [1 => 'int-key', 'foo' => 'bar'] —— '1' => 'string-key' 已被静默丢弃
-
array_merge() 对数字键的特殊逻辑
当输入数组含纯数字键（如 [0 => 'a', 2 => 'c']），array_merge() 不会覆盖，而是重新索引并追加：$a = [0 => 'a', 2 => 'c']; $b = [1 => 'b', 2 => 'd']; print_r(array_merge($a, $b)); // 输出: [0=>'a', 1=>'c', 2=>'b', 3=>'d'] —— 原键 2 被重置，语义完全丢失！
而 mergeWhen() 内部正是调用 array_merge() 实现合并。若你在资源的 toArray() 中构造了如下结构：
public function toArray(Request $request)
{
return [
'id' => $this->id,
0 => 'legacy_item', // 数字键
'name' => $this->name,
'email' => $this->when($this->relationLoaded('profile'), fn() => $this->profile->email),
// ⚠️ 此处若再用 mergeWhen([...])，PHP 将对整个数组执行 array_merge()
];
}一旦触发 mergeWhen()，PHP 会将整个数组视作待合并目标——此时混合键（'id' 字符串 + 0 数字）将触发上述转换与重排，轻则字段错位，重则关键数据（如 id）被覆盖或消失。
✅ 正确实践：保持键类型纯净
-
✅ 全字符串键（推荐）：语义清晰、无转换风险
return [ 'id' => $this->id, 'name' => $this->name, 'email' => $this->when($this->relationLoaded('profile'), fn() => $this->profile->email), ...$this->mergeWhen($this->isAdmin(), [ 'permissions' => $this->permissions, ]), ]; -
✅ 全连续数字键（仅限列表场景）：确保 0, 1, 2... 严格递增
// 用于 ResourceCollection 的自定义元数据（罕见，需谨慎） return [ 0 => $this->data, 1 => $this->meta, 2 => $this->links, ]; -
❌ 绝对避免：
// 错误示例：混合键 + 非连续数字键 → 不可预测结果 return [ 'id' => $this->id, 5 => 'out_of_order', 'status' => 'active', 0 => 'first', ];
? 总结
Taylor Otwell 的警告并非出于性能或安全考量，而是对 PHP 数组语言特性的务实规避：mergeWhen() 的可靠性完全依赖 array_merge() 的确定性行为，而混合键数组恰恰破坏了这种确定性。与其在生产环境遭遇静默数据丢失，不如从设计源头强制约束键类型——这既是 Laravel “约定优于配置”哲学的体现，也是构建健壮 API 的关键细节。
