PHP preg_match_all 按记录整理命名捕获组结果

我第一次把日志里的“键:值”片段交给 preg_match_all 时，最先踩到的不是正则写错，而是结果数组的形状不适合业务代码：默认结果按捕获组分列，遍历一次匹配却要同时拼接多个下标。需要按记录处理时，关键做法是给捕获组命名，再传入 PREG_SET_ORDER，让每次完整匹配成为一行记录。

官方地址：https://www.php.net/manual/en/function.preg-match-all.php

把 PREG_SET_ORDER 当作结果组织方式，而不是正则语法开关；再根据数据边界选择 PREG_UNMATCHED_AS_NULL 和 PREG_OFFSET_CAPTURE，就能稳定地整理命名字段、未匹配状态与原文位置。

这篇只处理四个具体问题：命名捕获组怎样按记录读取、可选组怎样区分“没匹配”和“匹配到空串”、偏移量怎样保存，以及匹配失败时怎样留下可检查的信号。

为什么 PREG_SET_ORDER 更适合按记录处理

不传排序标志时，preg_match_all 默认接近“按列”组织：$matches[0] 是所有完整匹配，命名组则分别保存同一列的值。这个形状适合统计某个字段出现了多少次，却不适合把一条匹配直接交给后续业务。

PREG_SET_ORDER 会把结果改成“按行”：$matches[0] 是第一条完整匹配及其捕获字段，$matches[1] 是第二条。命名键仍然存在，因此可以用字段名读取，而不必依赖捕获组的数字顺序。

[a-z]+)\s+value:\s*(?\d+)/i';

$count = preg_match_all($pattern, $subject, $matches, PREG_SET_ORDER);
if ($count === false) {
    // 正则编译或执行失败时保留明确的失败分支。
    throw new RuntimeException('正则匹配失败：' . preg_last_error());
}

$records = [];
foreach ($matches as $match) {
    // 使用命名键把一条匹配整理成业务记录。
    $records[] = [
        'full' => $match[0],
        'name' => $match['name'],
        'value' => (int) $match['value'],
    ];
}

print_r($records);
?>

这里的 $count 是完整模式匹配的数量，不是命名字段数量。把它与 false 严格比较，可以把“没有匹配到任何记录”和“正则执行失败”分开处理；前者是数量为 0，后者才是失败信号。

命名捕获组怎样让结果更容易维护

命名组可以写成 (?...)，也可以使用 (?P...)。在 PREG_SET_ORDER 下，同一条记录同时保留数字键和命名键，但业务层应优先依赖命名键。这样调整正则中其他非业务分组时，不容易把取值位置悄悄错位。

我通常会把正则负责“识别边界”，把数组整理负责“形成领域字段”。例如上面的 value 在整理阶段转成整数，原始完整匹配则保留在 full，便于排查输入与解析结果是否一致。不要在正则里塞入过多业务转换，否则后续很难判断是匹配问题还是类型转换问题。

如果同一模式存在重复命名组，还要特别谨慎：PHP 手册说明命名重复时命名键只保留最右侧子模式的值。需要保留多个候选时，应改用不同名称，或在业务层明确记录分支，而不要依赖重复名称覆盖。

未匹配组与偏移量怎么一起读取

可选捕获组是最容易产生歧义的地方。没有设置 PREG_UNMATCHED_AS_NULL 时，未参与匹配的组通常表现为空字符串；但“确实匹配到了空字符串”和“这条分支没有参与”并不是同一件事。加入这个标志后，未匹配组会以 null 表示，业务代码可以使用严格判断。

[\w.+-]+@[\w.-]+)|(?1\d{10}))/';
$flags = PREG_SET_ORDER | PREG_UNMATCHED_AS_NULL;

$count = preg_match_all($pattern, $subject, $matches, $flags);
if ($count === false) {
    // 失败时不要把半成品数组当作有效数据继续保存。
    throw new RuntimeException('正则匹配失败：' . preg_last_error());
}

foreach ($matches as $match) {
    // 严格判断可区分 null 与真实的空字符串。
    $email = $match['email'] ?? null;
    $phone = $match['phone'] ?? null;
    echo json_encode([
        'email' => $email,
        'phone' => $phone,
    ], JSON_UNESCAPED_UNICODE) . PHP_EOL;
}
?>

如果还需要知道字段在原文中的位置，可以叠加 PREG_OFFSET_CAPTURE。此时每个匹配值不再只是字符串，而是形如 [文本, 偏移量] 的数组；与 PREG_SET_ORDER 组合后，命名字段也遵循这个形状。

[^\s]+)\s+value:\s*(?\d+)/u';
$flags = PREG_SET_ORDER | PREG_UNMATCHED_AS_NULL | PREG_OFFSET_CAPTURE;

$count = preg_match_all($pattern, $subject, $matches, $flags);
if ($count === false) {
    // 记录错误码，调用方可以按错误类型决定是否重试。
    throw new RuntimeException('正则匹配失败：' . preg_last_error());
}

$record = $matches[0];
// 偏移量是字节位置，不是中文字符序号。
$nameText = $record['name'][0];
$nameByteOffset = $record['name'][1];
echo $nameText . ' @ byte ' . $nameByteOffset . PHP_EOL;
?>

PREG_OFFSET_CAPTURE 返回的是字节偏移，所以 UTF-8 文本里中文字段的偏移不能直接当作字符下标。需要按字符位置展示时，应在明确编码后再转换；需要做原文切片或回指时，则保持字节语义，并使用与之匹配的字符串函数。

我会保留的三个检查点

第一，调用方先严格判断返回值是否为 false，再处理数量为零的正常情况。第二，可选字段进入业务层前统一约定 null、空串和缺少键分别代表什么，避免后续把三种状态混为一谈。第三，只要保存了偏移量，就在字段名旁明确写出“byte”，不要把它命名成容易误解的 charIndex。

从安全角度看，正则结果本身也属于外部输入的整理结果：字段名、完整匹配和偏移量都不应直接拼进 HTML、SQL 或日志格式而跳过上下文编码。正则只负责识别，输出到不同系统时仍要遵循对应的转义和参数化规则。

简单速查：

相关问题

为什么遍历 PREG_PATTERN_ORDER 的结果很别扭？

因为它按捕获组分列保存，同一条匹配的多个字段分散在不同数组中。需要逐条处理时，用 PREG_SET_ORDER 让完整匹配成为记录边界更直接。

没有匹配到内容时应该判断 0 还是 false？

返回 0 表示模式有效但没有完整匹配，返回 false 才表示正则编译或执行失败。使用 === 判断，不要用宽松真假判断混在一起。

中文文本的偏移量为什么看起来偏大？

PREG_OFFSET_CAPTURE 给出的是字节偏移。UTF-8 中一个中文字符通常占多个字节，因此它不是可直接用于字符遍历的下标。