README

PHPMD 是 PHP Depend 的一个分支项目，旨在成为知名的 Java 工具 PMD 的 PHP 对等工具。PHPMD 可以被视为 PHP Depend 测量的原始指标流的用户友好的前端应用程序。

https://phpmd.org

安装

请参阅 https://phpmd.org/download/index.html

命令行使用

输入 phpmd [filename|directory[,filename|directory[,...]]] [report format] [ruleset file]，例如

mapi@arwen ~ $ phpmd php/PDepend/DbusUI/ xml rulesets.xml

虽然 rulesets.xml 规则集文件可能如下所示

<?xml version="1.0"?>
<ruleset name="My first PHPMD rule set"
         xmlns="https://phpmd.org/xml/ruleset/1.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="https://phpmd.org/xml/ruleset/1.0.0
                       http://phpmd.org/xml/ruleset_xml_schema_1.0.0.xsd"
         xsi:noNamespaceSchemaLocation="
                       http://phpmd.org/xml/ruleset_xml_schema_1.0.0.xsd">
  <description>
    My custom rule set that checks my code...
  </description>

  <rule ref="rulesets/codesize.xml" />
  <rule ref="rulesets/cleancode.xml" />
  <rule ref="rulesets/controversial.xml" />
  <rule ref="rulesets/design.xml" />
  <rule ref="rulesets/naming.xml" />
  <rule ref="rulesets/unusedcode.xml" />
</ruleset>

XML 报告可能如下所示

<?xml version="1.0" encoding="UTF-8" ?>
<pmd version="0.0.1" timestamp="2009-12-19T22:17:18+01:00">
  <file name="/projects/pdepend/PHP/Depend/DbusUI/ResultPrinter.php">
    <violation beginline="81"
               endline="81"
               rule="UnusedFormalParameter"
               ruleset="Unused Code Rules"
               externalInfoUrl="https://phpmd.org/rules/unusedcode.html#unusedformalparameter"
               priority="3">
      Avoid unused parameters such as '$builder'.
    </violation>
  </file>
</pmd>

您可以传递一个以逗号分隔的字符串，其中包含文件名列表或目录名，包含要传递给 PHPMD 的 PHP 源代码。

PHPMD Phar 发行版在其存档中包含了规则集文件，即使上面的 "rulesets/codesize.xml" 参数看起来像文件系统引用。

命令行选项

• 请注意，默认输出为 XML，因此您可以将其重定向到文件并使用 XSLT 或其他操作。

• 您还可以使用缩短的名称来引用内置规则集，如下所示

  phpmd PHP/Depend/DbusUI/ xml codesize
  

• 命令行界面还接受以下可选参数

  • --verbose, -v, -vv, -vvv - 输出详细程度。将打印更多关于正在处理或缓存的进程的信息。将发送到 STDERR 以不干扰报告输出。 text 输出还将每个错误旁边有一个链接到规则的文档，并以格式化位置的方式，大多数 IDE 都会将它转换为点击时打开错误行文件的链接。
  • --minimumpriority - 规则优先级阈值；优先级低于它们的规则将不会使用。
  • --reportfile - 将报告输出发送到指定的文件，而不是默认输出目标 STDOUT。
  • --suffixes - 以逗号分隔的有效源代码文件扩展名字符串，例如 php,phtml。
  • --exclude - 以逗号分隔的用于忽略目录的模式。使用星号按模式排除。例如 *src/foo/*.php 或 *src/foo/*
  • --strict - 也报告带有 @SuppressWarnings 注释的节点。
  • --ignore-errors-on-exit - 将以零代码退出，即使在出错时。
  • --ignore-violations-on-exit - 即使找到任何违规行为，也将以零代码退出。
  • --cache - 将启用结果缓存。默认为当前工作目录中的 .phpmd.result-cache.php。
  • --cache-file - 与 --cache 一起使用，将覆盖默认结果缓存文件路径 .phpmd.result-cache.php 为给定的文件路径。
  • --cache-strategy - 设置缓存策略以确定文件是否仍然新鲜。要么基于文件内容，要么基于文件修改时间戳。
  • --generate-baseline - 将为现有违规行为生成位于规则集定义文件旁边的 phpmd.baseline.xml。违规行为的文件路径相对于当前工作目录。
  • --update-baseline - 将从现有的 phpmd.baseline.xml 中移除所有不再存在的违规项。不会添加新违规项。违规项的文件路径相对于当前工作目录。
  • --baseline-file - 自定义基线 XML 文件的文件路径。如果不存在，则默认为 phpmd.baseline.xml
  • --color - 启用输出中的颜色，例如文本渲染器将以黄色显示规则名称，以红色显示错误描述。
  • --extra-line-in-excerpt - 指定在 HTML 格式的代码片段中添加多少额外行

  示例命令行

  phpmd PHP/Depend/DbusUI xml codesize --reportfile "phpmd.xml" --suffixes "php,phtml"
  

  选项可以在参数之前或之后。它们可以通过空格或等号（=）与它们的值分开。因此，以下语法与上一个语法等价

  phpmd --reportfile="phpmd.xml" --suffixes="php,phtml" PHP/Depend/DbusUI xml codesize
  

  以 - 开头的字符串将被识别为选项名称。如果您有以 - 开头的参数，请先设置选项，然后使用 -- 来标记显式的开始或参数列表

  phpmd --reportfile "phpmd.xml" --suffixes "php,phtml" -- -foo/Folder xml codesize
  

使用多个规则集

PHPMD 使用所谓的规则集来配置/定义一组规则，这些规则将应用于测试下的源代码。PHPMD 的默认分发已经包含了几个默认集，可以直接使用。您可以通过调用 PHPMD 的 CLI 工具并使用集的名称来应用此配置

~ $ phpmd /path/to/source text codesize

但如果您想对源代码应用多个规则集呢？您也可以将规则集名称的列表（以逗号分隔）传递给 PHPMD 的 CLI 工具

~ $ phpmd /path/to/source text codesize,unusedcode,naming

您还可以将自定义的 规则集文件 与内置规则集混合使用

~ $ phpmd /path/to/source text codesize,/my/rules.xml

就这样。使用这种行为，您可以指定要检查源代码的自定义规则集组合。

使用多个源文件和文件夹

PHPMD 还允许您指定多个源目录，如果您想为代码的某些部分创建一个输出

~ $ phpmd /path/to/code,index.php,/another/place/with/code text codesize

或使用 glob 模式

~ $ phpmd src/main/php/*/*/*{Renderer,Node}.php text my/rules.xml

扫描输入

PHPMD 还可以读取标准输入 stdin

~ $ cat src/MyService.php | phpmd - text my/rules.xml

因此，要扫描的 PHP 代码可能由另一个程序生成，不一定存储在文件中。

退出代码

PHPMD 的命令行工具当前定义了四个不同的退出代码。

• 0，此退出代码表示一切按预期进行。这意味着没有错误/异常，PHPMD 没有检测到测试代码中的任何规则违规。
• 1，此退出代码表示在执行期间发生了异常，这中断了 PHPMD。
• 2，此退出代码表示 PHPMD 在处理测试代码时没有发生错误/异常，但它已检测到分析源代码中的规则违规。您也可以使用 --ignore-violations-on-exit 标志来防止此行为，该标志即使发现违规也会导致 0

• 3，此退出代码表示由于错误，一个或多个测试文件无法

  被处理。可能还有其他文件中的违规，这些文件可以正确处理。

渲染器

目前 PHPMD 提供以下渲染器

• xml，将报告格式化为 XML。
• text，简单的文本格式。
• html，包含潜在问题的单个 HTML 文件。
• json，格式化 JSON 报告。
• ansi，一个适用于命令行的格式。
• github，GitHub Actions 可以理解的格式。
• gitlab，GitLab CI 可以理解的格式。
• sarif，静态分析结果交换格式。
• checkstyle，语言和工具无关的 XML 格式

基线

对于现有项目，可以生成违规基线。此基线中的所有违规将在进一步的检查中被忽略。

建议的方法是在项目的根目录中放置一个 phpmd.xml。为了生成其旁边的 phpmd.baseline.xml

~ $ phpmd /path/to/source text phpmd.xml --generate-baseline

为了指定用于导出的自定义基线文件路径

~ $ phpmd /path/to/source text phpmd.xml --generate-baseline --baseline-file /path/to/source/phpmd.baseline.xml

默认情况下，PHPMD 将在 phpmd.xml 旁边查找 phpmd.baseline.xml。要覆盖此行为

~ $ phpmd /path/to/source text phpmd.xml --baseline-file /path/to/source/phpmd.baseline.xml

清理现有的基线文件，仅删除不再存在的违规项

~ $ phpmd /path/to/source text phpmd.xml --update-baseline

PHPMD 企业版

作为 Tidelift 订阅的一部分提供。

PHPMD 的维护者以及数千个其他软件包的维护者正在与 Tidelift 合作，为您提供您在构建应用程序时使用的开源依赖的商业支持和维护。节省时间，降低风险，提高代码健康度，同时支付您所使用确切依赖项的维护者。了解更多信息。点击这里。

贡献

如果您想为 PHPMD 做贡献，请参阅贡献指南。