接口上线当晚,前端在群里发了一句「订单列表挂了」,附了一张控制台截图:TypeError: data.map is not a function。抓包看返回体,本来应该是一个数组,结果长成这样:
{"1":{"id":2,"status":"paid"},"2":{"id":3,"status":"paid"}}
后端代码看起来完全正常:从数据库取出列表,array_filter() 去掉已取消的订单,然后 json_encode() 返回。问题就出在 array_filter():它保留原数组的键。原本下标是 0、1、2,过滤掉第一个之后剩下 1、2,键不连续了,json_encode() 就把它编成了对象。
这个坑每年都有人踩,因为 PHP 的数组和大多数语言里的数组不是同一种东西。这篇讲清楚它到底是什么、常用函数分别怎么处理键、排序与合并有哪些语义差异,最后用一个订单列表接口把筛选、排序、分页走一遍。
PHP 数组是有序哈希表,不是「列表」
在 Java、Go、JavaScript 里,「列表」和「字典」是两种结构,键的类型也不一样。PHP 把两者合成一个:数组的键只能是非负整数或字符串,内部按插入顺序保存。所以同一个数组可以既像列表又像字典:
<?php
$mixed = [
0 => '第一项',
'name' => '科设',
2 => '第三项',
];
foreach ($mixed as $key => $value) {
echo "{$key}: {$value}\n";
}
// 0: 第一项
// name: 科设
// 2: 第三项
顺序是插入顺序,不会自动按数字大小排。这一点很关键:PHP 的数组更像「有序字典」,array_values()、array_keys() 都保留这个顺序,所以经常被拿来当队列用。
两个细节容易被忽略。第一,纯数字字符串键会自动转成整数,$a['1'] 和 $a[1] 是同一个位置;带前导零的字符串 '01' 不转。第二,给数组追加元素时,下一个整数键是「当前最大整数键加一」,不是元素个数。删掉中间元素再追加,新键不会填补空洞。
<?php
$a = [0 => 'a', 1 => 'b', 2 => 'c'];
unset($a[1]);
$a[] = 'd';
var_dump(array_keys($a)); // [0, 2, 3]
这就解释了为什么 array_filter() 之后会留下空洞:它不重建键。要得到「从 0 开始连续」的列表,必须显式 array_values()。
json_encode() 判断一个数组输出为 JSON 数组还是对象,看的不是「声明方式」,而是键:键是 0 到 n-1 连续整数时输出为数组,否则输出为对象。空数组 [] 输出为 [],不是 {}。声明、访问与合并
短数组语法 [] 从 PHP 5.4 就有了,现在不该再写 array()。访问用方括号,取嵌套值用 ?? 兜底;PHP 8 的 nullsafe 只用于对象,数组还是要一层层判断。
<?php
$order = [
'id' => 1024,
'user' => ['name' => '小林', 'vip' => false],
];
echo $order['user']['name'] ?? '匿名'; // 小林
echo $order['user']['phone'] ?? '未填写'; // 未填写
合并数组有三种写法,语义完全不同:
| 写法 | 数字键 | 字符串键 | 适用场景 |
|---|---|---|---|
array_merge($a, $b) | 重新编号追加 | 后者覆盖前者 | 合并两个列表,或合并配置项 |
$a + $b | 后者不覆盖已有序号 | 后者不覆盖已有键 | 给默认值补缺,不覆盖已有配置 |
[...$a, ...$b] | 重新编号追加 | 后者覆盖前者 | PHP 8.1 起可用,写法更直观 |
数字键重排最典型的表现是:两个各含三条记录的列表用 array_merge() 合并,结果长度是六,键从 0 排到 5。如果本意是拿第二个列表覆盖第一个列表里同 id 的数据,得到的却是一份重复列表,后面按 id 取值全乱。想按 id 合并,得先用 array_column($rows, null, 'id') 建成映射,再 array_replace()。
最常见的错误是拿 array_merge() 合并两份带数字键的列表,以为能去重或者覆盖,结果变成了更长的列表。反过来,用 + 合并配置时它是「只补不覆盖」,很多人以为右边优先,实际是左边优先,排查起来很费时间。
展开运算在 PHP 8.1 之前只能展开数字键数组,8.1 起支持字符串键,但仍不支持重复字符串键的语义争议,团队里用之前先确认版本。需要明确覆盖行为时,array_replace() 更直白:右边覆盖左边,数字键和字符串键都一样。
筛选、映射、聚合
三个最常用的函数:array_map() 对每个元素做转换,返回新数组且保留原来的键;array_filter() 按条件筛选,保留键;array_reduce() 把数组折叠成一个值。
<?php
$prices = [1990, 2990, 3990];
// 全部转成带两位小数的字符串
$formatted = array_map(fn (int $c): string => number_format($c / 100, 2), $prices);
// 只要 3000 分以下的
$cheap = array_filter($prices, fn (int $c): bool => $c < 3000);
// 求和
$total = array_reduce($prices, fn (int $carry, int $c): int => $carry + $c, 0);
var_dump($formatted); // ['19.90', '29.90', '39.90']
var_dump(array_values($cheap)); // [1990, 2990]
var_dump($total); // 8970
array_filter() 不传回调时会去掉所有「假值」,包括 0、"0"、空字符串和 null。这个默认行为在生产里非常危险:一个金额为 0 的记录会被静默丢掉。永远传一个明确的回调,不要图省事。
array_filter() 的回调还能同时拿到键和值,第三个参数传 ARRAY_FILTER_USE_BOTH 或 ARRAY_FILTER_USE_KEY。用它筛键比先 array_flip() 更直接。
同一类问题里,in_array() 的第三个参数最该形成肌肉记忆。默认松散比较,in_array(0, ['0']) 返回 true,in_array(' 1', [1]) 也返回 true,因为带前导空格的数字字符串在 PHP 里算合法数字格式。更要命的是它跨版本不稳定:PHP 8 改了数字与字符串的比较规则,同一段判断在 7.4 和 8.2 上可能一个放行、一个拒绝。有团队用 in_array($type, ['image', 'video']) 做上传类型白名单,后来白名单改成从数据库读,值变成了带前缀的字符串,判断语句一个字没改,行为却变了。
反过来也有事故:有人补上了第三个参数 true,但白名单里存的是 ['1', '2', '3'],请求参数在入口已经被强转成 int。严格比较下 1 !== '1',所有合法值全部被拒,用户一直看到「类型不支持」。这种情况浏览器里看不出异常,接口照样返回 200,只是业务提示错误,最后是临时加了 var_dump($type, $whitelist) 才看到一个是 int(1)、一个是 string(1) "1"。结论很朴素:要么先把类型统一再严格比较,要么干脆转成键用 isset() 查,别让「松散还是严格」变成每个人的个人习惯。
从数据库结果里抽一列,用 array_column():
<?php
$rows = [
['id' => 1, 'email' => 'a@example.com'],
['id' => 2, 'email' => 'b@example.com'],
];
$emails = array_column($rows, 'email');
$byId = array_column($rows, null, 'id'); // 变成以 id 为键的映射
array_column($rows, null, 'id') 是个很好用的技巧:把结果集按主键重排,之后按 id 取值不用再循环搜。它还能处理对象数组(读公有属性),从 PHP 7.0 起就能用。
判断键存不存在时,isset($arr[$key]) 和 array_key_exists($key, $arr) 在值为 null 时结果不同:前者返回 false,后者返回 true。判断「有没有这个键」用后者,判断「有没有值」用前者。配置合并的逻辑常在这里出错,表现为某个默认值被 null 覆盖后,下一次判断认为键不存在,又把默认值补了回来。
排序:键留不留,差别很大
PHP 的排序函数分成两大类:一类按值排,一类按键排;每类又分「保留键」和「重建键」。用错了,数据看起来排好了,关联关系却断了。
| 函数 | 按什么排 | 键是否保留 | 常见用途 |
|---|---|---|---|
sort() / rsort() | 值 | 重建为 0..n-1 | 纯列表排序 |
asort() / arsort() | 值 | 保留 | 映射按值排序后仍要按原键取 |
ksort() / krsort() | 键 | 保留 | 按 id、按日期排序的映射 |
usort() / uasort() | 自定义回调 | usort 重建,uasort 保留 | 按对象字段、按多条件排序 |
用 usort() 写多条件排序时,宇宙飞船运算符 <=> 很好用,返回 -1、0、1。PHP 8.0 起所有排序都是稳定的:值相等时,原来在前的仍然在前。这个保证在旧版本里没有,升级后某些列表顺序会变,属于预期行为。
<?php
usort($orders, function (array $a, array $b): int {
return [$b['amount'], $a['createdAt']] <=> [$a['amount'], $b['createdAt']];
});
上面按金额降序、时间升序。数组比较是按元素依次比,写起来比一堆 if 清楚。注意 usort() 会重建键,如果后面还要按订单 id 取,用 uasort()。
比较函数写错最常见的一种,是顺手写成布尔表达式:
<?php
// 错:返回 bool,usort 需要 -1 / 0 / 1 三态
usort($orders, fn (array $a, array $b): bool => $a['amountCents'] > $b['amountCents']);
// 对:用飞船运算符
usort($orders, fn (array $a, array $b): int => $a['amountCents'] <=> $b['amountCents']);
PHP 8 会在第一次比较时打一条 Deprecated: usort(): Returning bool from comparison function is deprecated,但不会中断执行。true 被当成 1、false 被当成 0,「小于」的情况永远返回 0,排序器会认为两个元素相等,于是结果不是完全没排,而是局部有序、局部错位。三条数据肉眼看着没问题,二十条以上就开始乱,同样的数据两次排出来的顺序甚至可能不一样。这种 bug 只在线上全量数据里露头,本地小样本永远是对的。看到这条 Deprecated 就当场改,别等它变成事故。
排序还有一个性能边界:usort() 是 O(n log n),但回调会被调用很多次。回调里别查数据库、别读文件。需要按数据库字段排序时,让 SQL 的 ORDER BY 来做,别把全量数据捞回内存再排。
多维数组与分组统计
后台报表最常见的需求:按状态统计订单数和金额。用一次循环加空合并赋值就能做:
<?php
$orders = [
['status' => 'paid', 'amountCents' => 19900],
['status' => 'paid', 'amountCents' => 29900],
['status' => 'cancelled', 'amountCents' => 9900],
];
$stats = [];
foreach ($orders as $order) {
$status = $order['status'];
$stats[$status] ??= ['count' => 0, 'amountCents' => 0];
$stats[$status]['count']++;
$stats[$status]['amountCents'] += $order['amountCents'];
}
print_r($stats);
输出里 paid 是 2 单、49800 分,cancelled 是 1 单、9900 分。??= 是 PHP 7.4 的写法,意思是「不存在或为 null 时才赋值」,比 isset($stats[$status]) ? ... : ... 短得多。
多维数组的坑在于「修改副本」。PHP 数组赋值是写时复制,$b = $a 之后改 $b 不会影响 $a;但如果你在 foreach 里对嵌套数组整体赋值,容易只改了副本。要批量修改,用引用或者生成新数组,别指望「传进去就能改」。
如果数据来自数据库,这种分组统计最好交给 SQL 的 GROUP BY,PHP 只负责格式化。把几万行捞回来在 PHP 里循环,内存和 CPU 都吃不消,这也是第 7 篇要讲的分工。
去重也要注意语义。array_unique() 保留第一次出现的键,默认按字符串比较,1 和 "1" 会被当成同一个;对二维数组直接用它没有意义,因为数组转字符串会报 Array to string conversion。按某个字段去重,通常用字段值做键重建数组:array_column($rows, null, 'email'),同邮箱只留最后一条,具体留第一条还是最后一条要按业务确认。
场景走查:订单列表接口
需求:给后台返回订单列表,支持按状态筛选、按金额从高到低排序、分页,每页 20 条。
第一版很直接:查全量,array_filter() 筛状态,usort() 排金额,array_slice() 取当前页,json_encode() 返回。本地数据只有十几条,一切正常。上线后前端报 data.map is not a function——因为筛选把键留空了。
第二版在返回前加了 array_values():
<?php
$page = max(1, (int) ($_GET['page'] ?? 1));
$perPage = 20;
$all = $repository->findAll(); // 示例,真实实现是 SQL 查询
$filtered = array_filter(
$all,
fn (array $o): bool => $o['status'] === 'paid'
);
$filtered = array_values($filtered);
usort($filtered, fn (array $a, array $b): int => $b['amountCents'] <=> $a['amountCents']);
$total = count($filtered);
$pageItems = array_values(array_slice($filtered, ($page - 1) * $perPage, $perPage));
header('Content-Type: application/json; charset=utf-8');
echo json_encode([
'data' => $pageItems,
'total' => $total,
'page' => $page,
'perPage' => $perPage,
], JSON_UNESCAPED_UNICODE);
第三版把「先全量再内存分页」改成了真正的 SQL 分页加 ORDER BY,PHP 这边只负责整理字段和输出。原因很简单:订单涨到十万条后,第二版每次请求都要把全表捞进内存,响应从几十毫秒涨到几秒,最后直接 502。这个改动的细节在第 7 篇。
上线后又碰到一个边界:筛选结果为空时,$pageItems 是 [],json_encode() 输出 [],前端能正常处理。但空数组永远输出 [],如果接口约定某个字段是对象,得显式写 (object) [],否则前端拿到的是数组而不是对象。这种「空值形态」最好在接口文档里写死,别让前端靠猜。
把这次事故的修复前后摆在一起看,差别只有一层括号。假设五个订单里第一个和第四个被筛掉:
<?php
$all = [['id' => 1], ['id' => 2], ['id' => 3], ['id' => 4], ['id' => 5]];
$kept = array_filter($all, fn (array $o): bool => $o['id'] !== 1 && $o['id'] !== 4);
echo json_encode($kept, JSON_UNESCAPED_UNICODE), "\n";
// {"1":{"id":2},"2":{"id":3},"4":{"id":5}}
echo json_encode(array_values($kept), JSON_UNESCAPED_UNICODE), "\n";
// [{"id":2},{"id":3},{"id":5}]
元素一个都没少,变的只是外面的括号。前端报的 data.map is not a function 不是「数据错了」,而是「形状错了」,所以只看数据库有没有数据会完全误判。也见过有人为了「统一返回对象」在输出层加 JSON_FORCE_OBJECT,结果所有列表接口一起变成对象,一处问题扩散成全站问题,这个参数别在公共输出层用。
本地验证不用起整个项目。把上面几行存成 check.php 执行 php check.php,第一行必须以 {"1" 开头、第二行必须以 [ 开头;两行都是 [ 说明 array_values() 生效了,都带数字键说明漏了。要在真实请求上确认,用内置服务器跑一个最小接口:
php -S 127.0.0.1:8080 router.php
curl -s "http://127.0.0.1:8080/orders?page=1" | head -c 80
通过的标准是返回体以 {"data":[{ 开头,而不是 {"data":{"0" 或 {"data":{"1"。这一步比在浏览器里看到「有数据」可靠,因为前端框架往往自动把对象包一层,肉眼分辨不出结构和数组的差别。
现象、原因与第一步
| 现象 | 真实原因 | 第一步查什么 |
|---|---|---|
接口返回对象,前端 map 报错 | array_filter 等函数保留了不连续的键 | 对结果加 array_values(),再 json_encode |
| 数字字符串键取不到值 | PHP 把纯数字字符串键自动转成了整数 | 打印 array_keys(),统一用整数键或加前缀 |
| 合并后数据莫名消失 | 用 + 合并,右边不覆盖左边 | 确认用的是 array_merge、array_replace 还是 + |
| 排序后按 id 取不到数据 | sort/usort 重建了数字键 | 换 asort/uasort,或排序前先建 id 映射 |
in_array 明明没这个值却返回 true | 默认松散比较,"1" 命中 1 | 第三个参数传 true,或改用键查找 |
| 金额为 0 的记录被筛掉 | array_filter 不传回调,按假值过滤 | 检查回调是否写了明确的布尔条件 |
| 遍历时删除元素漏掉后一项 | foreach 遍历的是副本,删除不改变当前遍历 | 先收集要删的键,循环结束后统一 unset |
| 大数组导致内存超限 | 数组本身开销大,且 array_map 又复制一份 | 看 memory_limit 报错行;改分批或生成器 |
边界与代价
PHP 数组很好用,但内存开销不低。一个元素除了值本身,还要存键、哈希槽、顺序信息,几万个元素的数组可能占几十兆。批量处理大文件或大结果集时,用生成器逐条产出,比一次性 file() 或全量查询稳得多。
array_map、array_filter 每次调用都会生成新数组,原数组还在内存里,峰值是两份。数据量不大时这是最清晰的写法;数据量大时,用 foreach 原地构建结果,或者 yield。
键保留这个设计本身没有对错:分组统计时你需要键,列表输出时你需要重建。问题在于很多函数默认保留,而 JSON 和前端默认期待连续下标。养成一个习惯:给外部输出的列表,最后一定过一遍 array_values()。
in_array 是线性查找,几万条里反复查会明显变慢。需要频繁判断「在不在集合里」时,先把数组转成 array_flip() 的结果,再用 isset(),复杂度从 O(n) 降到接近 O(1)。如果不打算给 in_array 传第三个参数 true,判断还会走宽松比较,'0' 和 0、'1 '(末尾带空格)和 1 都可能被认成同一个,结果是「明明不在白名单里却被放行」。凡是拿它做权限或白名单判断,第三个参数必须写 true。
还有两个同源的坑。array_search() 返回的是键,命中第一个元素时返回 0,找不到返回 false,所以写成 if ($pos = array_search($needle, $arr)) 时,键 0 和字符串键 "0" 都会被判成假,「明明存在却说没有」。正确写法是 if (($pos = array_search($needle, $arr)) !== false),比较符号不能省成一个等号。另一个是 array_unique(),默认按字符串比较,1、"1"、1.0 会被当成同一个,最后留下哪个类型取决于谁先出现;后面若还要做严格比较,类型可能已经变了。
最后一个容易忽略的细节:array_slice() 默认会重建数字键,但字符串键一定保留。所以对关联数组切片后直接 json_encode(),仍然可能得到对象。规则记不住没关系,记住一个动作:要交给前端当列表用的数组,输出前过一遍 array_values()。
另一个坑是引用。 foreach ($rows as &$row) { $row['name'] = trim($row['name']); } 写起来很方便,但循环结束后 $row 仍然是最后一个元素的引用。后面再用一次 foreach ($rows as $row),第二次循环会把值写回最后一个元素,数据被悄悄改掉。规范做法是引用循环结束后立刻 unset($row),或者干脆不用引用,改成按下标赋值。这类问题不带报错,只在结果里出现一两条不对的数据,非常难查。
解构赋值是另一个顺手但容易忽略的写法:[$a, $b] = $pair 按位置取值,['name' => $name] = $row 按键取值。键不存在时会发警告,不能靠 ?? 兜住,所以解构前要确认结构。它适合处理固定形状的返回值,不适合不可信的外部数据。
当天能自己验证的练习
- 运行
json_encode(array_filter([1, 2, 3], fn ($n) => $n > 1)),看输出是数组还是对象;加上array_values()再试一次。 - 写一个订单数组,用
foreach按状态分组,统计每组的单数和金额,和手算结果核对。 - 用
array_column($rows, null, 'id')把结果集转成映射,再用 id 直接取值。 - 分别用
sort、asort、usort排同一个数组,打印array_keys(),确认哪种保留了键。 - 用
array_merge、+、array_replace合并两个带相同字符串键的配置数组,比较结果差异。
小结
三句话:PHP 数组是有序哈希表,列表和字典是同一个东西;筛选、排序之后键可能不连续,对外输出前过一遍 array_values();合并和排序的每个函数都有一套自己的键规则,用之前先确认。
下一篇讲面向对象。今天写的 $order['status']、$order['amountCents'] 这种数组,字段全靠记忆和注释。项目一大,有人写 amount,有人写 total,接口就悄悄坏了。下一篇从这种「字段名靠猜」的问题开始,讲类、接口、构造器提升和枚举怎么把结构固定下来。