ECC 规则体系实战：为 Claude Code 配置 PHP 专属 Hooks，实现自动格式化、静态分析与安全告警-平芜编程栈

ECC 规则体系实战：为 Claude Code 配置 PHP 专属 Hooks，实现自动格式化、静态分析与安全告警

【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC

本篇技术指南聚焦于 ECC（Everything Claude Code）规则体系中 PHP 专属的 Hooks 规则（docs/ja-JP/rules/php/hooks.md，源规则见 rules/php/hooks.md），讲解如何基于 Claude Code 的 Hook 事件机制，为 PHP 项目配置「编辑后自动格式化、静态分析、定向测试」三大 PostToolUse 检查，以及针对调试残留与安全回归的告警规则。读完本文，你将能够在~/.claude/settings.json中落地一套可复制的 PHP Hooks 配置，并结合仓库内真实 Hook 实现（scripts/hooks/、hooks/hooks.json）理解其底层原理。

一、规则定位：PHP Hooks 在 ECC 规则体系中的角色

ECC 是一个面向 Claude Code、Codex、Opencode、Cursor 等 Agent 环境的 harness 优化系统，其rules/目录按语言与横向主题组织了大量规则文档。每条语言规则通过 frontmatter 中的paths声明生效范围，例如 PHP 规则只在与下列路径相关的文件上激活：

--- paths: - "**/*.php" - "**/composer.json" - "**/phpstan.neon" - "**/phpstan.neon.dist" - "**/psalm.xml" ---

这套声明意味着：只要 Agent 会话涉及.php源文件、Composer 清单或 PHPStan/Psalm 静态分析配置，PHP 专属规则就会被加载。PHP 的 Hooks 规则并非孤立文件，而是明确继承自通用 Hooks 规则——原文中> This file extends [common/hooks.md](https://link.gitcode.com/i/2260589398049e1032b6b47218ca0f61) with PHP specific content.（对应仓库根路径为 rules/common/hooks.md），因此在理解 PHP 专属部分之前，需要先掌握通用的 Hook 事件模型。

二、Hook 事件模型：PreToolUse / PostToolUse / Stop 与生命周期钩子

通用 Hooks 规则（rules/common/hooks.md）将 Claude Code 的 Hook 分为三类核心事件，而仓库内的 hooks/README.md 进一步补充了完整的生命周期视角：

事件	触发时机	能力边界
PreToolUse	工具执行前	可校验、可修改参数；exit code 2 可阻断工具调用，仅输出 stderr 则只告警不阻断
PostToolUse	工具执行后	自动格式化、运行检查；只能分析输出，无法阻断
Stop	每次 Agent 响应结束后	最终校验（如批量化格式化与类型检查、console.log 审计、会话状态持久化）
SessionStart / SessionEnd	会话生命周期边界	加载历史上下文、会话结束清理
PreCompact	上下文压缩前	保存状态，防止信息丢失

整个数据流可以概括为：用户请求 → Agent 选择工具 → PreToolUse 钩子运行 → 工具执行 → PostToolUse 钩子运行。ECC 仓库自身即大量使用这套机制：在 hooks/hooks.json 中可以看到PreToolUse的 Bash 预检分发器（pre:bash:dispatcher）、PostToolUse的同步/异步分发器（post:dispatcher:sync / async）、以及Stop事件下的批量化格式与类型检查（stop:format-typecheck）。PHP 专属 Hooks 规则正是要在这套通用事件模型之上，叠加 PHP 技术栈特有的检查动作。

三、PHP PostToolUse Hooks：格式化、静态分析、定向测试三件套

PHP Hooks 规则的核心内容是在~/.claude/settings.json中配置PostToolUse钩子，针对每次编辑后的.php文件自动执行三项检查。规则原文列出的三组工具组合，恰好对应 PHP 工程质量的三个维度：格式规范、类型安全、行为正确。

3.1 自动格式化：Pint / PHP-CS-Fixer

Pint / PHP-CS-Fixer: Auto-format edited.phpfiles.

编辑完成的.php文件应立即被格式化，避免 Agent 生成与项目风格不一致的代码。这与 rules/php/coding-style.md 中「使用 PHP-CS-Fixer 或 Laravel Pint 进行格式化」的规范直接呼应——两者都是基于 PSR-12 的格式化器，Pint 是 Laravel 官方维护、更强调零配置开箱即用的选择，PHP-CS-Fixer 则提供更细粒度的规则集定制。

这一行为在仓库内的 JS/TS 版本已有成熟实现可参考：scripts/hooks/post-edit-format.js。该实现的核心模式是：

解析 stdin 传入的 Hook JSON，取出tool_input.file_path；
用正则匹配文件扩展名（该文件匹配\.(ts|tsx|js|jsx)$，PHP 版对应改为\.php$）；
向上查找项目根目录，自动探测项目使用的格式化器（Biome/Prettier，PHP 版对应探测 Pint/PHP-CS-Fixer）；
优先调用本地node_modules/.bin（PHP 版对应vendor/bin）下的可执行文件，避免解析开销；
格式化失败时静默失败、非阻断——格式化工具未安装或失败都不应中断 Agent 主流程。

3.2 静态分析：PHPStan / Psalm

PHPStan / Psalm: Run static analysis after PHP edits in typed codebases.

在类型化代码库中，PHP 编辑之后应运行静态分析，尽早暴露类型错误。PHPStan 与 Psalm 是 PHP 生态的两大主流静态分析器，ECC 的 PHP 代码评审 Agent（agents/php-reviewer.md）也把二者列为评审前置步骤，并给出了可直接使用的诊断命令：

./vendor/bin/phpstan analyse --level max # 类型安全与错误（level max 为最高严格级别） ./vendor/bin/psalm --show-info=true # 静态分析，显示 info 级信息

静态分析配置本身即被 PHP 规则 frontmatter 的paths覆盖（phpstan.neon、phpstan.neon.dist、psalm.xml），说明规则作者把「分析配置」也纳入了 Agent 的监控范围——当这些文件被改动时，同样应触发 PHP 相关检查。

3.3 定向测试：PHPUnit / Pest

PHPUnit / Pest: Run targeted tests for touched files or modules when edits affect behavior.

当编辑影响行为时，应针对被改动文件或所属模块运行定向测试，而不是全量跑测试套件——这是控制 Agent 工作循环耗时的重要策略。测试框架的选择遵循 rules/php/testing.md 的约定：PHPUnit 为默认框架；若项目已配置 Pest，则新测试优先使用 Pest，且避免混用两套框架。

常用命令：

vendor/bin/phpunit --filter=TargetTest --coverage-text # PHPUnit 定向测试 # 或 vendor/bin/pest --filter=TargetTest --coverage # Pest 定向测试

该规则还建议在 CI 中保持覆盖率阈值（优先 pcov 或 Xdebug），让覆盖率要求成为机器可执行的硬性门槛。

四、一份可直接落地的`~/.claude/settings.json`配置示例

将上述三件套组合进 Claude Code 的 Hook 配置（JSON 结构与 hooks/hooks.json 中matcher → hooks[] → type/command的层级一致）：

{ "hooks": { "PostToolUse": [ { "matcher": "Edit|Write", "hooks": [ { "type": "command", "command": "php -r \"$d=stream_get_contents(STDIN);$i=json_decode($d,true);$f=$i['tool_input']['file_path']??'';if(preg_match('/\\.php$/',$f)){exec('vendor/bin/pint '.escapeshellarg($f));}echo $d;\"" } ], "description": "Auto-format edited PHP files with Laravel Pint" }, { "matcher": "Edit|Write", "hooks": [ { "type": "command", "command": "php -r \"$d=stream_get_contents(STDIN);$i=json_decode($d,true);$f=$i['tool_input']['file_path']??'';if(preg_match('/\\.php$/',$f)&&is_file('phpstan.neon')){exec('vendor/bin/phpstan analyse '.escapeshellarg($f).' --no-progress');}echo $d;\"" } ], "description": "Run PHPStan on edited PHP files when phpstan.neon exists" } ] } }

关键点说明（对应 hooks/README.md 的 Hook 协议）：

stdin/stdout 协议：Hook 是 shell 命令，从 stdin 读取 JSON（含tool_name、tool_input.file_path、tool_output等字段），并必须将原始数据回写到 stdout；
matcher 匹配：Edit|Write表示对编辑与新建文件都生效，如需更精确可只用Edit；
退出码语义：0表示成功继续；2表示阻断（仅 PreToolUse 有效）；其他非零视为错误（记日志但不阻断）——因此 PostToolUse 的格式化、分析钩子失败时应以非阻断方式处理，避免拖垮 Agent 主流程；
路径安全性：直接拼接 shell 命令存在注入风险，生产环境建议仿照 scripts/hooks/post-edit-format.js 的做法，对文件路径做 shell 元字符过滤（该文件用正则/[&|<>^%!;()$]/` 拒绝不安全路径）。

注意：以上为贴合规则意图的示例配置，实际命令需按项目依赖（Pint/PHP-CS-Fixer、PHPStan/Psalm、PHPUnit/Pest 的 vendor 路径）与所在平台（Windows/macOS/Linux）调整。

五、警告规则：调试残留、原始 SQL 与安全回退

PHP Hooks 规则的第二部分定义了 PostToolUse 钩子的告警职责，即不阻断、但必须提醒 Agent 与用户注意的代码质量问题：

5.1 调试残留：var_dump / dd / dump / die()

Warn onvar_dump,dd,dump, ordie()left in edited files.

var_dump()、Laravel 的dd()、Symfony 的dump()以及die()都是典型的调试残留，一旦进入提交会产生输出污染甚至中断请求。ECC 的 PHP 评审 Agent 在 MEDIUM 优先级检查项中同样列出「dd()/dump()/var_dump()left in committed code」（见 agents/php-reviewer.md），规则与评审工具在此形成闭环：PostToolUse 钩子负责即时告警，评审 Agent 负责在代码审查阶段把关。

仓库中Stop事件的check-console.log钩子（见 hooks/hooks.json 与 scripts/hooks/check-console-log.js）正是同类「残留扫描」思路——它在每次响应后检查被修改文件中的console.log，PHP 版本只需把扫描目标换成上述四个 PHP 调试函数。

5.2 安全回归：原始 SQL 与 CSRF/会话保护

Warn when edited PHP files add raw SQL or disable CSRF/session protections.

两类安全回退必须被标记：

原始 SQL：在控制器或视图中拼接 SQL 字符串是 SQL 注入的温床。这与 rules/php/security.md 的「数据库安全」条款完全一致——所有动态查询应使用预处理语句（PDO、Doctrine、Eloquent query builder），避免在控制器/视图中手工拼接 SQL，ORM 批量赋值（mass-assignment）应严格白名单化$fillable可写字段；
禁用 CSRF/会话保护：如移除 CSRF 中间件、关闭 session、绕过框架内置的请求令牌校验等操作，属于高危变更。security.md明确要求：密码存储使用password_hash()/password_verify()，认证与权限变更后必须重新生成会话标识符，状态变更类 Web 请求必须强制 CSRF 保护。PostToolUse 钩子应在编辑内容中检测这些模式的痕迹并发出告警。

从 rules/php/hooks.md 的paths可见，composer.json也被纳入监控——依赖变更同样可能引入安全风险，security.md建议在 CI 中运行composer audit检查依赖漏洞，并审慎评估新增维护者的可信度。

六、自动批准权限：只信任明确计划，禁用跳过校验

通用 Hooks 规则（rules/common/hooks.md）对自动批准权限给出了严格的边界，这部分同样适用于 PHP 场景（尤其是上述「自动格式化、自动跑测试」这类会产生副作用的钩子）：

仅在可信、定义清晰的计划下启用自动批准；
探索性工作中禁用自动批准——此时 Agent 的行为不可预期，盲目放行会掩盖错误；
绝不使用dangerously-skip-permissions标志跳过所有权限校验；
取而代之，在~/.claude.json中通过allowedTools精确声明允许的工具白名单，例如只放行Bash(pint:*)、Bash(phpstan:*)、Bash(phpunit:*)等具体命令前缀，而不是整类放行。

七、TodoWrite 最佳实践：让多步任务可追踪

PHP 修复往往横跨「格式化 → 静态分析 → 定向测试 → 修复告警」多个步骤，通用 Hooks 规则建议使用TodoWrite工具跟踪多步骤任务的进度：

跟踪多步任务的进度，防止遗漏；
验证 Agent 是否正确理解指令；
支持实时调整执行方向；
展示细粒度的实现步骤。

同时，Todo 列表本身也是一面镜子——它能暴露顺序错误的步骤、缺失的项目、多余的项目、粒度不当、以及被误解的需求。对于 PHP Hooks 流水线而言，合理的 Todo 分解示例为：1) 用 Pint 格式化改动文件 → 2) 运行 PHPStan 静态分析 → 3) 对受影响模块跑 PHPUnit/Pest → 4) 扫描调试残留与安全回退并修复。

八、运行时控制：不修改配置即可开关钩子

ECC 的 Hook 运行时（hooks/README.md）为钩子提供了环境变量级的控制面，避免为了临时调整而反复编辑 JSON 配置：

# 总开关：显式环境变量优先于插件偏好 export ECC_HOOKS_ENABLED=true # 运行档位：minimal | standard | strict（默认 standard） export ECC_HOOK_PROFILE=standard # 按 ID 禁用特定钩子（逗号分隔） export ECC_DISABLED_HOOKS="pre:bash:tmux-reminder,post:edit:typecheck" # 禁用 GateGuard（仅限搭建或恢复阶段） export ECC_GATEGUARD=off

三个档位的语义：

minimal—— 只保留必要的生命周期与安全钩子；
standard—— 默认档，质量与安全检查平衡；
strict—— 启用更多提醒与更严格的护栏。

在 PHP 项目中，若某次会话只想跑格式化不想跑静态分析，可以借助ECC_DISABLED_HOOKS精确关闭对应钩子，而不必改动~/.claude/settings.json。若以插件方式安装，则通过ecc setup --mode claude-plugin管理hooks_enabled与hook_profile偏好。

九、进阶：参照仓库实现编写你自己的 PHP Hook

仓库的 hooks/README.md 提供了完整的自研 Hook 模板（my-hook.js骨架），其要点是：从 stdin 读取 JSON、解析tool_name/tool_input/tool_output、按需向 stderr 输出告警、最后把原始数据回写 stdout。基于此，你可以为 PHP 定制更精细的检查，例如：

TODO 告警：在new_string中匹配TODO|FIXME|HACK并提醒创建 issue；
测试伴随检查：新建 PHP 源文件时检查同名测试文件是否存在，缺失则提示先写测试（呼应 rules/php/testing.md 与tdd-workflow的 RED→GREEN→REFACTOR 循环）；
大文件阻断：Write时统计行数，超过阈值（如 800 行）时以 exit code 2 阻断，引导拆分为更聚焦的模块。

如需完整了解本仓库的 Hook 架构、安装方式（bash ./install.sh --target claude --modules hooks-runtime --enable-hooks）与全部内置钩子清单，可继续阅读 hooks/README.md，并对照 hooks/hooks.json 与 rules/common/hooks.md。PHP 相关的兄弟规则（编码风格 rules/php/coding-style.md、安全 rules/php/security.md、测试 rules/php/testing.md）以及评审 Agent agents/php-reviewer.md 与本规则共同构成了完整的 PHP 工程质量闭环。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

ECC 规则体系实战：为 Claude Code 配置 PHP 专属 Hooks，实现自动格式化、静态分析与安全告警