PHPStan 错误标识符 `regexp.pattern` 详解：静态校验 preg_* 正则表达式，让无效模式在运行前暴露

• 开发工具
• 代码质量
• 静态分析

导读

regexp.pattern是 PHPStan 在分析阶段检测到传给preg_*系列函数的正则表达式模式无效、无法被 PCRE 引擎编译时报告的错误标识符。本文以 website/errors/regexp.pattern.md 为核心，结合仓库中的错误标识符注册表与相关规则源码，讲解该错误的触发场景、底层原理、修复方式，以及如何通过配置管理与忽略这类错误。读完本文，你将掌握如何借助 PHPStan 在运行代码之前定位正则语法错误，并理解这一类"静态可解析的正则校验"在 PHPStan 规则体系中的定位。

一、什么是regexp.pattern错误标识符

在 PHPStan 中，每个可报告的错误都带有一个稳定的标识符（identifier），用于在 CI 输出、基线（baseline）和ignoreErrors配置中精确引用。regexp.pattern的官方定义如下（见 website/errors/regexp.pattern.md 的 frontmatter）：

• title：regexp.pattern
• shortDescription："Regular expression pattern is invalid and would fail at runtime."（正则表达式模式无效，运行时会失败）
• ignorable：true（表示该错误可以被显式忽略，例如写入 ignoreErrors 或基线文件）

从错误标识符注册表 website/src/errorsIdentifiers.json 可以看到，该标识符对应两条规则实现：

• PHPStan\Rules\Regexp\RegularExpressionPatternRule（来自phpstan/phpstan-src主仓库，即本仓库对应的源码规则）；
• PHPStan\Rule\Nette\RegularExpressionPatternRule（来自phpstan/phpstan-nette扩展包，为 Nette 框架集成场景提供同一标识符的错误）。

也就是说，regexp.pattern是一个跨主仓库与扩展包统一使用的标识符，无论规则来自核心还是扩展，错误输出中的标识符始终保持一致，便于统一管理。

这些错误文档文件由仓库维护工作流依据errorsIdentifiers.json生成，其结构规范定义在 website/errors/CLAUDE.md：每个文件都包含Code example（触发代码）、Why is it reported?（原因说明）、How to fix it（修复方式）三个固定章节。

二、触发该错误的代码示例

原文档给出了最小触发用例：

<?php declare(strict_types = 1); $result = preg_match('/[unclosed/', 'test');

这里向preg_match()传入的模式/[unclosed/存在语法问题：开头的[表示字符类（character class），但直到模式结束都没有对应的]来关闭它。当 PHP 运行到这一行时，PCRE 引擎将无法编译该模式并抛出警告/错误，函数调用直接失败。

从该错误标识符的名称与语义可知，PHPStan 只会在模式在分析阶段能够被静态解析（即字面量或可确定的常量）时执行此校验；如果模式来自无法在静态分析时确定值的变量，PHPStan 则无法验证，也就不会报告regexp.pattern。

三、为什么会报告该错误

3.1 底层原理：PCRE 编译失败

PHP 的preg_*系列函数（preg_match、preg_replace、preg_split、preg_grep等）依赖 PCRE 正则引擎。当模式传入时，引擎会先对模式进行编译：解析元字符、检查定界符、构建匹配内部状态机。一旦模式存在语法错误，编译就会失败，函数调用在运行期产生preg_match(): Compilation failed之类的警告并返回false或null，而不会按预期执行匹配。

PHPStan 的RegularExpressionPatternRule会在分析阶段对模式做同样的编译校验。从实现角度看，这条规则是 PHPStan 众多"无需运行代码即可发现 bug"的规则之一，与 PHPStan 的核心定位（"在编写测试之前就捕获整类 bug"）一致。

3.2 常见触发原因

原文档归纳了几类高频诱因，结合 PCRE 语法可展开如下：

• 缺少闭合定界符：如'/foo少了结尾的/（定界符必须成对出现，常见于字符串拼接或复制粘贴遗漏）；
• 括号不匹配：字符类[...]、分组(...)、量词{...}未成对闭合，如示例中的/[unclosed/；
• 无效的转义序列：如\x后未跟合法十六进制数、\c后未跟合法控制字符、\p{...}属性名拼写错误；
• 其他 PCRE 语法错误：如量词位置错误、向后引用越界、命名分组重名、非法修饰符（如/.../z中z不是合法修饰符）等。

这些错误在运行时才会暴露，若代码路径未被测试覆盖，往往难以察觉；PHPStan 通过静态校验将其提前到分析阶段。

四、如何修复：完整修复示例

原文档给出两种修复思路，均使用diff-php格式展示改动。

方案一：转义字符类开括号（当[表示字面量时）

如果业务意图是匹配字面量[，需要转义：

<?php declare(strict_types = 1); -$result = preg_match('/[unclosed/', 'test'); +$result = preg_match('/\[unclosed/', 'test');

方案二：关闭字符类（当[确实要作为字符类时）

如果意图是匹配字符类[unclosed]中的任一字符，则补上闭合括号：

<?php declare(strict_types = 1); -$result = preg_match('/[unclosed/', 'test'); +$result = preg_match('/[unclosed]/', 'test');

原文档还建议：在应用修复前，用 regex101 之类的正则调试工具验证修正后的模式是否匹配预期字符串（注意：此处仅为文档建议的工作流提示，不构成项目声明）。

修复要点

• 修改后应重新运行 PHPStan 确认regexp.pattern消失，并补跑涉及该函数的单元测试，确保行为符合预期；
• 如果模式由多个片段拼接而成，检查拼接处是否引入了未转义元字符，必要时使用preg_quote()处理用户输入部分。

五、与相关标识符的联动：argument.invalidPregQuote

regexp.pattern不是 PHPStan 中唯一与正则相关的静态校验。仓库中同类的错误文档还有 website/errors/argument.invalidPregQuote.md，它针对preg_quote()的定界符参数缺失或错误：

preg_match("/" . preg_quote($input) . "/", "test");

preg_quote()会转义正则特殊字符，但若没有把定界符作为第二个参数传入，拼接后的模式仍可能包含未转义的定界符/，从而破坏整个模式——这正是regexp.pattern所报告的"无效模式"的一类典型来源。修复方式是传入正确的定界符：

-preg_match("/" . preg_quote($input) . "/", "test"); +preg_match("/" . preg_quote($input, "/") . "/", "test");

这两个标识符通常配合出现：argument.invalidPregQuote提醒你正确转义动态内容，regexp.pattern兜底校验最终拼接出的整体模式是否可编译。在涉及用户输入构建正则的场景中，同时关注两者能显著降低运行期正则崩溃的风险。

六、如何管理与忽略该错误

由于regexp.pattern的 frontmatter 中ignorable: true，它支持 PHPStan 标准的错误抑制机制：

1. ignoreErrors 配置：在phpstan.neon中按标识符精确忽略（参考 website/src/user-guide/ignoring-errors.md）。需要注意，忽略应谨慎使用——regexp.pattern几乎总是代表真实的模式 bug，忽略后运行期依然会失败；
2. 基线（baseline）：通过--generate-baseline将现存错误快照进基线文件，逐步清理（参考 website/src/user-guide/baseline.md）。基线适用于历史存量代码的渐进式修复，而非新代码的豁免。

最佳实践是：新代码中出现的regexp.pattern一律直接修复模式本身，不要通过配置压制；仅在确认为第三方代码或无法静态解析的特殊场景下考虑豁免。

七、小结与速查

把正则校验交给静态分析，是 PHPStan "不运行代码就能发现 bug" 理念的典型落地：一条原本只在运行时闪过的 PCRE 警告，如今在 CI 阶段就以确定性错误的形式呈现。遇到regexp.pattern，优先修复模式语法，让代码在运行前就保持正确。

• 开发工具
• 代码质量
• 静态分析