PHP preg_match_all 怎样提取命名分组

我在处理配置文本和日志行时，最先改掉的通常不是正则本身，而是 $matches[1]、$matches[2] 这种难以维护的读取方式。preg_match_all 支持命名捕获分组：给子表达式取一个名字后，结果数组除了保留数字下标，还会增加同名键。这样做的价值是让“第几个括号”变成“我要的字段”。

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

本文只讨论命名分组的提取方式、结果排列和边界处理。结论先说：使用 (?...) 或等价语法命名字段；逐条处理匹配时优先用 PREG_SET_ORDER；需要把同一个字段集中成一列时用 PREG_PATTERN_ORDER。

先给捕获字段一个稳定的名字

命名分组有三种常见写法，PHP 手册给出的三种形式都表示同一个意图：

• (?Ppattern)
• (?pattern)
• (?'name'pattern)

实际项目里我更常用第二种，因为它和很多 PCRE 示例的视觉结构比较接近。命名只负责“这个括号捕获什么”，不会改变正则的匹配范围，也不会让外层非捕获分组自动变成字段。

[a-z]+):\s*(?\d+)/';
$subject = "a: 1\nb: 2\nc: 3";
$matches = [];

// 中文注释：返回完整匹配数，结果同时包含 name、digit 和数字下标。
$count = preg_match_all($pattern, $subject, $matches);

if ($count === false) {
    // 中文注释：正则编译或执行失败时，不把部分结果当成成功数据。
    throw new RuntimeException('正则表达式执行失败');
}

echo $matches['name'][0] . PHP_EOL;
echo $matches['digit'][0] . PHP_EOL;
?>

命名捕获不会删除数字下标。以默认的 PREG_PATTERN_ORDER 为例，$matches[0] 是完整匹配列，$matches['name'] 和 $matches['digit'] 是命名字段列，同时还会保留对应的数字分组。代码里因此可以直接使用字段名，而不必记住它在括号里的位置。

结果按列还是按记录排列

命名分组提取时，第二个容易踩到的边界是结果的排列方向。默认的 PREG_PATTERN_ORDER 把结果按“字段列”组织，$matches['name'] 是所有 name，$matches['digit'] 是所有 digit。它适合统计、批量取一列或只关心某个字段的场景。

PREG_SET_ORDER 则把结果按“每次完整匹配”组织：$matches[0]['name'] 与 $matches[0]['digit'] 属于第一条记录，$matches[1] 属于第二条记录。我的经验是，只要后面要把字段装进对象、数组或数据库行，就优先选择这种形状。

[a-z]+):\s*(?\d+)/';
$subject = "a: 1\nb: 2\nc: 3";
$rows = [];

$matched = preg_match_all($pattern, $subject, $rows, PREG_SET_ORDER);
if ($matched === false) {
    // 中文注释：失败时立即停止，避免继续处理不完整的结果数组。
    throw new RuntimeException('无法提取键值记录');
}

foreach ($rows as $row) {
    // 中文注释：命名键描述业务字段，数字键只用于兼容底层匹配结构。
    printf("%s => %d%s", $row['name'], (int) $row['digit'], PHP_EOL);
}
?>

这里的强制转换只服务于示例输出。如果数字字符串要参与金额、范围或数据库类型判断，应先完成业务层校验，再决定是否转成整数；命名分组本身不会替你完成数据类型转换。

一个完整例子：提取重复的键值文本

下面把输入、模式、结果和异常处理放在一起。模式只允许小写字母作为字段名，冒号后允许空白，再捕获十进制数字。这样边界是明确的：不符合格式的文本不会被“猜测式”解析。

[a-z]+):\s*(?\d+)/';
$subject = "alpha: 10\nbeta: 20\ninvalid line";
$matches = [];

$count = preg_match_all($pattern, $subject, $matches, PREG_SET_ORDER);
if ($count === false) {
    // 中文注释：false 表示正则错误，不等价于“零条匹配”。
    throw new RuntimeException('正则模式无效');
}

if ($count === 0) {
    // 中文注释：零条匹配是正常业务结果，和执行失败分开处理。
    echo "没有符合格式的记录" . PHP_EOL;
} else {
    foreach ($matches as $match) {
        // 中文注释：使用命名键读取字段，避免依赖捕获括号的数字顺序。
        echo $match['name'] . ': ' . $match['digit'] . PHP_EOL;
    }
}
?>

返回值要分成三个情况：大于零表示找到完整匹配，零表示执行成功但没有匹配，false 表示正则模式没有成功编译或执行。把零和 false 混为一谈，会让排错信息失真。

可选分组不要只看空字符串

当命名分组位于可选结构里时，字段可能没有参与某一次匹配。默认情况下，未匹配的子模式会以空字符串出现在结果中；如果调用时加入 PREG_UNMATCHED_AS_NULL，则会以 null 表示。对于“空值”和“没有出现”必须区分的接口，后者更容易被业务代码识别。

[a-z]+)(?::\s*(?\d+))?/';
$subject = "alpha: 10\nbeta";
$matches = [];

$count = preg_match_all(
    $pattern,
    $subject,
    $matches,
    PREG_SET_ORDER | PREG_UNMATCHED_AS_NULL
);

if ($count === false) {
    // 中文注释：先处理正则失败，再读取任何命名字段。
    throw new RuntimeException('可选字段模式执行失败');
}

foreach ($matches as $match) {
    // 中文注释：NULL 表示没有参与匹配，字符串“0”仍然是有效数字文本。
    $digit = $match['digit'];
    echo $match['name'] . ' => ' . ($digit === null ? '无数字' : $digit) . PHP_EOL;
}
?>

如果不使用 PREG_UNMATCHED_AS_NULL，就不要把空字符串一律当成数据缺失：正则也可能真的匹配了一个允许为空的表达式。需要保留这种差异时，优先让模式和 flags 共同表达语义。

输入和正则模式的安全边界

命名分组解决的是结果可读性，不会自动解决输入风险。生产代码里可以把下面几条边界固定下来：

• 外部文本可以作为 $subject，但不要把未经限制的外部字符串直接拼成 $pattern。
• 需要动态匹配字面量时，先根据实际语义使用 preg_quote，不要把用户输入当成正则语法执行。
• 字段名、长度和允许字符要有上限，尤其是批量处理长文本时，避免无边界的回溯成本。
• 对返回值同时判断 === false 和 === 0，并在日志中记录模式来源，而不是记录敏感原文。
• 同一个模式里不要随意复用命名分组；PHP 手册说明，重复命名时命名键只保留最右侧子模式的结果。

这也是我选择命名分组的原因：当模式需要调整时，字段的读取意图更容易审查，输入边界和输出边界可以分开讨论。

最后的速查结论

如果只是从文本中批量拿出几个字段，命名分组和默认列式结果已经够用；如果每条匹配要进入后续业务处理，PREG_SET_ORDER 通常更直观。真正需要迁移的不是某个数字下标，而是把模式、输入约束和结果语义一起固定下来。

相关问题

• 为什么命名键和数字键会同时存在？ 命名分组是在原有捕获分组编号之外增加一个可读索引，便于按字段语义读取。
• 没有匹配时应该看什么？ 看 preg_match_all 的返回值；零是没有完整匹配，false 才是模式执行失败。
• 逐条处理和按字段处理怎么选？ 逐条组装记录用 PREG_SET_ORDER，集中取某个字段用默认的 PREG_PATTERN_ORDER。