PHP preg_replace_callback_array 怎样按模式分发替换逻辑

我第一次把几类文本清洗规则放在同一段 PHP 代码里时，最容易写成一个很长的回调：先判断标签，再判断电话号码，最后判断空白。规则一多，回调就变成了分支表。preg_replace_callback_array 更适合这个场景：用“正则模式 => 回调”组织规则，让每个回调只负责一种匹配。

官方手册：https://www.php.net/manual/en/function.preg-replace-callback-array.php

它的关键不是“把多个回调同时跑起来”，而是按关联数组中的模式逐组处理当前 subject。前一个模式产生的新文本，会成为后一个模式继续处理的输入。因此规则顺序就是设计的一部分。

先把每类匹配交给自己的回调

下面的例子把 HTML 片段中的标签、手机号和连续空白分别交给三个回调。示例只表达代码结构，不代表在本机执行过的运行证据。

]+>~' => function (array $match): string {
        // 标签统一替换为空格，避免相邻文字黏在一起。
        return ' ';
    },
    '~(? function (array $match): string {
        // 手机号只保留前后各两位，示例中间值不应继续流向正文。
        return substr($match[0], 0, 2) . '******' . substr($match[0], -2);
    },
    '~\s+~' => function (array $match): string {
        // 最后一条规则收拢连续空白，保持段落可读。
        return ' ';
    },
];

$text = '
联系 13800138000
';
$clean = preg_replace_callback_array($rules, $text, -1, $count);

if ($clean === null) {
    // 非法正则会返回 null，并可能触发 E_WARNING；生产代码要记录规则来源。
    throw new RuntimeException('文本规则编译失败');
}

echo trim($clean); // 结果是普通字符串，count 是所有规则完成的替换次数。
?>

这里最值得记住的是第三个参数。-1 表示每个模式在每个 subject 中不限制替换次数；如果只想替换每类规则的前两处，可以传入 2。官方定义是“每个模式、每个 subject 的最大替换次数”，不是整个调用的总次数。

什么时候值得用它，什么时候连续调用更清楚

我通常先看规则是否有明确的“模式—处理器”对应关系。如果每条规则都有独立职责，preg_replace_callback_array 让新增规则只需要增加一项；如果所有匹配都共享上下文，单个 preg_replace_callback 反而更直接。

一个常见误区是把它理解为“对同一个原始字符串并行匹配”。实际使用中，模式数组按顺序逐组应用；前面回调返回的文本会进入后面的模式。因此，如果第一条规则把占位符改成了后面规则能匹配的文本，后面规则仍可能继续处理它。

规则顺序、count 和数组 subject 要一起设计

当规则之间可能互相影响时，我会先写一张小表，明确每一组的输入和输出。一般把结构性替换放在前面，把收尾清理放在后面；不要依赖回调之间的全局变量传递“当前处理到哪里”。

 function (array $match): string {
        // 先保留语义标记，后续清理规则不会把它当普通文本处理。
        return '《' . trim($match[1]) . '》';
    },
    '~[ \t]+~' => function (array $match): string {
        // 只收拢横向空白，不吞掉换行结构。
        return ' ';
    },
];

$subjects = [
    '[重要] 版本说明 [/重要]',
    '普通    说明',
];

$count = 0;
$result = preg_replace_callback_array($rules, $subjects, -1, $count);
if ($result === null) {
    // 数组 subject 出错时仍以 null 判断失败，不把它当成空数组。
    throw new RuntimeException('规则未能应用');
}
// 返回值与 subject 同形：输入是数组，结果也是数组。
print_r($result);
?>

数组 subject 是另一个容易漏掉的边界：传入字符串就返回字符串，传入字符串数组就返回数组。count 统计替换总数，适合写入日志或做粗粒度告警，但它不告诉你是哪条规则命中了多少次；如果需要分规则统计，应该在各回调中显式记录，或拆成独立调用。

未匹配和错误返回值不要混为一谈

没有匹配项时，PHP 会返回原 subject；正则编译失败时返回 null，并可能发出 E_WARNING。因此不要只写 if (!$result)，因为空字符串、空数组和 null 的含义不同。

回调也应该稳定返回字符串。外部输入参与正则构造时要先固定规则来源并做好转义，不能把未经约束的用户文本直接拼进模式；这属于输入设计问题，不是换一个回调函数就能解决的。

我的选择结论

需要多种正则模式、每种模式都有独立处理逻辑时，我会优先选 preg_replace_callback_array，并把规则顺序写进测试用例和代码注释。只有一个模式、多个模式共享状态，或者每一步都代表独立业务阶段时，单回调或连续调用更容易维护。

• 想按规则职责拆分回调：选择 preg_replace_callback_array。
• 想共享状态并统一决定替换内容：选择单个 preg_replace_callback。
• 想让每一步可单独观测和回滚：拆成连续调用。

相关问题

preg_replace_callback_array 的规则会并行执行吗？

不会。模式—回调对按数组顺序逐组应用，前一组生成的文本可能成为后一组的输入。

没有匹配时应该判断什么？

用 $count === 0 判断本次没有发生替换，用 $result === null 判断执行失败，不要用宽松布尔判断代替。

输入是数组时返回什么？

输入是字符串数组时返回字符串数组；输入是普通字符串时返回字符串。两种形态都要按严格类型处理。