在 Debian 上配置 PHPStorm 的代码审查工具

一 准备环境

工欲善其事，必先利其器。配置之前，先把基础环境搭建好。这里以 Debian 12 为例。

• 安装 PHP 与 Composer：这是后续所有工具的基石。
  • 打开终端，执行：sudo apt update && sudo apt install -y php-cli composer
• 全局安装代码规范与自动修复工具：推荐全局安装，这样所有项目都能受益，管理起来也方便。
  • composer global require “squizlabs/php_codesniffer=*”
  • composer global require “friendsofphp/php-cs-fixer”
• 确认可执行文件路径：这一步很关键，后面在 PHPStorm 里配置时需要用到。
  • 查看全局 bin 目录：composer global config bin-dir --absolute
  • 进入该目录看看，应该能找到 phpcs、phpcbf、php-cs-fixer 这几个可执行文件。

对了，本文的配置示例以 PSR-2 标准为主。如果你的团队或项目要求使用 PSR-12，只需要把后续配置中间出现的 “PSR-2” 替换成 “PSR-12” 即可，操作逻辑完全一致。

二 在 PHPStorm 内配置 PHPCS 实时检查

接下来，让代码规范检查“活”在编辑器里，实现实时反馈。

• 关联 PHPCS 可执行文件：
  • 打开 PHPStorm 设置：File → Settings → Languages & Frameworks → PHP → Quality Tools → Code Sniffer。
  • 在 Configuration 区域点击 “…” 按钮，找到并选择你之前确认的 phpcs 可执行文件的完整路径，然后点击 Validate 验证通过。
• 启用实时检查：
  • 继续在设置中定位到：Editor → Inspections → PHP → Quality Tools。
  • 勾选上 PHP Code Sniffer validation。
  • 在右侧的 Coding standard 下拉菜单中，选择 PSR-2（或者你项目正在使用的其他标准）。

配置完成后，效果立竿见影：任何不符合规范的代码行，编辑器都会用醒目的波浪线标出。把鼠标悬停上去，就能看到具体的违规提示。这相当于请了一位严格的代码审查员，时刻坐在你旁边。

三 配置保存时自动修复与一键修复

光发现问题还不够，高效修复才是提升生产力的关键。这里提供两种主流方案，你可以根据习惯选择。

• 方案一：外部工具 + 快捷键（通用且稳定）
  • 打开设置：Settings → Tools → External Tools，点击 “+” 号添加。
  • 新建一个工具，关键参数如下：
    • Name：起个易懂的名字，比如 PHP-CS-FIX。
    • Program：填入你的 PHP 可执行文件路径（终端执行 which php 可获得）。
    • Parameters：/path/to/php-cs-fixer fix “$FilePath$” --rules=@PSR2（注意替换为你的实际路径）。
    • Working directory：$ProjectFileDir$。
  • 使用起来很方便：在项目中的文件或目录上右键，选择 External Tools → PHP-CS-FIX 即可。更进一步，可以为这个操作设置一个快捷键（比如 Ctrl+Alt+L），实现“一键美化代码”。
• 方案二：File Watcher（保存即触发）
  • 首先确保安装了 File Watchers 插件（首次使用需在 Marketplace 搜索安装）。
  • 然后新建一个 Watcher：
    • File type：选择 PHP。
    • Scope：选择 Project Files。
    • Program：填入 php-cs-fixer 的绝对路径。
    • Arguments：fix “$FilePath$” --rules=@PSR2。
    • Output paths to refresh：可以留空或填 $FilePath$。
    • Trigger the watcher on：务必勾选 On Sa ve（保存时）。

这样一来，每次保存 PHP 文件，它都会自动按照规则格式化，简直省心。另外提一句，phpcbf（PHP Code Beautifier and Fixer）也能实现类似的“按规则修复”功能，用法和 php-cs-fixer 大同小异。团队可以根据规范偏好，选择其一或组合使用。

四 提交前强制门禁与团队协作

个人本地检查固然重要，但如何确保团队每个成员提交的代码都符合规范？这就需要一道“强制门禁”。GrumPHP 正是为此而生，它能在 Git 提交前自动运行检查，不通过则直接阻止提交。

• 安装与初始化：
  • 在项目根目录执行：composer require --dev phpro/grumphp
  • 然后初始化配置：vendor/bin/grumphp init
• 配置要点：
  • 编辑生成的 grumphp.yml 文件，一个简单的示例如下：

    parameters:
      git_dir: .
      bin_dir: vendor/bin
      tasks:
        phpcs:
          standard: PSR2
          ignore_patterns:
            - ./database/*
            - ./vendor/*
    

配置完成后，每次执行 git commit 命令，GrumPHP 都会自动触发 PHPCS 检查。只有代码完全符合 PSR2 规范，提交才会成功。这相当于在仓库门口设置了一位铁面无私的保安。

五 常见问题与排查

配置过程很少一帆风顺，遇到问题别慌，通常都能快速解决。

• PHPStorm 提示找不到 phpcs/phpcbf/php-cs-fixer：
  • 首先在终端执行 which phpcs（或 which phpcbf / which php-cs-fixer），将返回的绝对路径准确填入 PHPStorm 的配置项。
  • 如果命令本身不存在，请检查 Composer 的全局 bin 目录是否已加入系统的 PATH 环境变量，并尝试重新安装对应工具。
• 编码标准不生效或下拉列表为空：
  • 在 PHPStorm 的 Code Sniffer 配置页，点击 Validate 按钮重新验证。
  • 在 Inspections 页面，尝试点击“刷新”按钮来加载可用的标准列表。
  • 如果还不行，可以在项目根目录创建一个 phpcs.xml 配置文件，或者在命令行中显式使用 @PSR2 来指定标准。
• 保存文件时未触发自动修复：
  • 如果使用 External Tool 方案，检查其 Working directory 是否设置为 $ProjectFileDir$。
  • 如果使用 File Watcher，确认触发条件勾选了 On Sa ve，并检查项目路径是否存在权限问题。
• 如何保证团队标准统一：
  • 将团队约定的代码规范配置文件（如 phpcs.xml 或 .php-cs-fixer.dist.php）提交到版本仓库中。
  • 确保本地 PHPStorm 的检查规则、GrumPHP 的提交前检查，乃至持续集成（CI）流程，都引用仓库中的同一份配置文件。这才是保证“千人一面”的关键所在。