PHP Code Sniffer 配置：实现仅扫描指定目录的高级排除策略

本文详细介绍了如何在php code sniffer的`.phpcs.xml`配置文件中，通过精确的正则表达式配置``，实现仅对项目中的特定目录进行代码检查。通过这种高级排除策略，开发者可以有效缩小扫描范围，提升代码质量检查的效率和精准度，避免不必要的代码扫描，确保资源集中在核心代码上。

PHP Code Sniffer 扫描范围管理概述

PHP Code Sniffer (PHPCS) 是一个强大的代码风格和质量检查工具。通过项目根目录下的 .phpcs.xml 配置文件，我们可以定义扫描规则、文件类型以及最重要的——扫描范围。exclude-pattern 标签允许我们指定要从扫描中排除的文件或目录模式。然而，当需求是“只扫描某些目录，排除所有其他内容”时，配置会变得稍复杂，需要利用正则表达式的强大功能。

挑战：仅包含指定目录的扫描

在许多项目中，开发者可能只希望对项目中的特定子目录（例如，自定义插件目录或主题目录）进行代码质量检查，而忽略其他大量无关文件或第三方库。直接的 <exclude-pattern> 配置通常用于排除已知的不需要扫描的目录。但要实现“只扫描指定目录”的反向逻辑，需要一个能够匹配“所有不属于指定目录的文件路径”的正则表达式。

最初的尝试可能类似于：

<exclude-pattern>^(?!wp-content\/plugins\/customplugin\/*$|wp-content\/themes\/customtheme\/*$).+</exclude-pattern>

这种模式的意图是使用负向先行断言 (?!...) 来排除那些不以 wp-content/plugins/customplugin/ 或 wp-content/themes/customtheme/ 开头的路径。然而，这种模式通常无法按预期工作，因为它没有正确处理路径的完整性和深度，可能导致 PHPCS 扫描不到任何文件。

立即学习“PHP免费学习笔记（深入）”；

解决方案：使用高级正则表达式精确排除

要正确实现“只扫描指定目录”的目标，我们需要一个能够识别“任何不包含指定目录路径”的文件路径，并将其排除的正则表达式。以下是有效的解决方案：

笔目鱼英文论文写作器

写高质量英文论文，就用笔目鱼

87

查看详情

<exclude-pattern>^(?!.*\/wp-content\/plugins\/customplugin|.*\/wp-content\/themes\/customtheme).*</exclude-pattern>

让我们详细解析这个正则表达式的构成：

• ^: 匹配文件路径的开始。
• (?!...): 这是一个负向先行断言。它表示只有当紧随其后的内容不匹配括号内的模式时，整个表达式才匹配。
• .*\/: 这是关键部分。
  • .*: 匹配任意数量的任意字符（包括零个）。
  • \/: 匹配一个正斜杠。
  • 结合起来，.*\/ 允许在目标目录路径之前存在任意数量的父级目录，例如 project/src/wp-content/... 或 vendor/some-lib/wp-content/...。这使得模式能够适应不同深度的文件路径。
• wp-content\/plugins\/customplugin: 这是我们希望 不被排除 的目标目录之一。请注意斜杠需要转义。
• |: 逻辑或操作符，用于连接多个不被排除的目录模式。你可以根据需要添加更多目录。
• .*: 在负向先行断言之后，匹配文件路径的剩余部分。如果整个文件路径不符合负向先行断言（即，它不包含任何一个我们希望扫描的目录模式），那么它就会被 .* 匹配，从而被 <exclude-pattern> 排除。

简而言之，这个正则表达式的含义是：“排除所有这样的路径，它们从开头到结尾不包含 wp-content/plugins/customplugin 或 wp-content/themes/customtheme 这样的子路径。”

完整的 .phpcs.xml 配置示例

将上述正则表达式集成到 .phpcs.xml 文件中，示例如下：

<?xml version="1.0"?>
<ruleset name="MyProjectCustomStandard">
    <description>Custom standard for My Project, focusing on specific directories.</description>

    <!-- 定义要扫描的基础路径。通常设置为项目根目录。 -->
    <file>.</file>

    <!-- 设置要排除的模式，以实现只包含指定目录的目的。
         此模式将排除所有不包含 'wp-content/plugins/customplugin' 或
         'wp-content/themes/customtheme' 作为其路径一部分的文件。
    -->
    <exclude-pattern>^(?!.*\/wp-content\/plugins\/customplugin|.*\/wp-content\/themes\/customtheme).*</exclude-pattern>

    <!-- 引用或定义你的代码规范。例如 PSR12。 -->
    <rule ref="PSR12"/>

    <!-- 你可以在这里添加更多的规则或 Sniff。 -->
    <!-- <rule ref="MyCustomSniff"/> -->

    <!-- 可以进一步排除特定文件类型，如果它们不属于上述目录。
         例如，排除根目录下的所有 .md 文件，除非它们在包含的目录中。
         但请注意，上面的 exclude-pattern 已经非常强大，可能会覆盖这些。
    -->
    <!-- <exclude-pattern>*.md</exclude-pattern> -->

</ruleset>

使用此配置后，当您运行 phpcs 命令时，它将仅扫描 wp-content/plugins/customplugin/ 和 wp-content/themes/customtheme/ 目录及其子目录下的 PHP 文件。

注意事项与最佳实践

1. 路径分隔符： 在正则表达式中，使用 \/ 来匹配路径分隔符，以避免与正则表达式中的特殊字符冲突。
2. 目录层级： .*\/ 的使用至关重要，它确保了无论目标目录位于文件路径的哪个深度，都能被正确识别。
3. 正则表达式测试： 建议使用在线正则表达式测试工具（如 Regex101.com）来验证您的模式是否按预期工作，尤其是在添加更多目录或调整模式时。
4. 性能考量： 尽管正则表达式在大多数情况下效率很高，但过于复杂或宽泛的模式可能会对大型项目的扫描性能产生轻微影响。在实际使用中，通常这种影响可以忽略不计。
5. 未来发展： PHP Code Sniffer 项目一直在发展。根据 GitHub 上的相关讨论（例如 issue #1884），未来可能会引入更直接或更易于配置的方式来实现“仅包含”特定目录的功能。建议关注官方文档和更新，以便在有更优方案时进行调整。
6. 多目录扩展： 如果需要包含更多目录，只需在负向先行断言内部使用 | 运算符继续添加模式，例如：

   ^(?!.*\/dir1|.*\/dir2|.*\/dir3).*

   登录后复制

总结

通过在 .phpcs.xml 中巧妙地运用负向先行断言和 .*\/ 组合的正则表达式，我们可以实现对 PHP Code Sniffer 扫描范围的精确控制，使其仅对项目中的特定目录进行检查。这种方法极大地提高了代码质量检查的针对性和效率，确保开发资源集中在核心代码的维护上。在配置时，理解正则表达式的每个部分并进行充分测试是成功的关键。

以上就是PHP Code Sniffer 配置：实现仅扫描指定目录的高级排除策略的详细内容，更多请关注php中文网其它相关文章！