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

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

一 准备环境

• 安装 PHP 与 Composer（Debian 12 示例）：
  • 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 实时检查

• 打开设置：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；也可为该项设置快捷键，便于保存时快速修复
• 方案二（File Watcher，保存自动触发）
  • 安装 File Watchers 插件（首次使用需在 Marketplace 安装）
  • 新建 Watcher：
    • File type：PHP
    • Scope：Project Files
    • Program：/path/to/php-cs-fixer
    • Arguments：fix “$FilePath$” --rules=@PSR2
    • Output paths to refresh：留空或填 $FilePath$
    • Trigger the watcher on：勾选保存时（On Save）
• 说明：phpcbf 也可用于批量“按规则修复”，用法与 php-cs-fixer 类似，可按团队规范选择其一或配合使用。

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

• 使用 GrumPHP 在 Git 提交时自动执行 PHPCS 检查，未通过则阻止提交：
  • 安装：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 都会自动运行 PHPCS，只有符合规范才会通过。

五 常见问题与排查

• 找不到 phpcs/phpcbf/php-cs-fixer：在终端执行 which phpcs（或 which phpcbf / which php-cs-fixer），将返回的绝对路径填入 PHPStorm 配置；若命令不存在，请确认 Composer 全局 bin 已加入 PATH，并重新安装对应工具
• 标准不生效或下拉为空：在 Code Sniffer 配置页点击 Validate；在 Inspections 页面点击 刷新 按钮以加载可用标准；必要时在项目根目录添加 phpcs.xml/使用 @PSR2 显式指定标准
• 保存未触发修复：检查 External Tool 的 Working directory 是否为 $ProjectFileDir$；File Watcher 需确保触发条件为 “On Save”，且项目路径无权限问题
• 团队标准统一：将 phpcs.xml 或 .php-cs-fixer.dist 提交到仓库，并在 GrumPHP 中引用相同标准，保证本地与 CI 一致。