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本篇技术指南聚焦于 ECCEverything 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-FixerPint / 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/PrettierPHP 版对应探测 Pint/PHP-CS-Fixer优先调用本地node_modules/.binPHP 版对应vendor/bin下的可执行文件避免解析开销格式化失败时静默失败、非阻断——格式化工具未安装或失败都不应中断 Agent 主流程。3.2 静态分析PHPStan / PsalmPHPStan / Psalm: Run static analysis after PHP edits in typed codebases.在类型化代码库中PHP 编辑之后应运行静态分析尽早暴露类型错误。PHPStan 与 Psalm 是 PHP 生态的两大主流静态分析器ECC 的 PHP 代码评审 Agentagents/php-reviewer.md也把二者列为评审前置步骤并给出了可直接使用的诊断命令./vendor/bin/phpstan analyse --level max # 类型安全与错误level max 为最高严格级别 ./vendor/bin/psalm --show-infotrue # 静态分析显示 info 级信息静态分析配置本身即被 PHP 规则 frontmatter 的paths覆盖phpstan.neon、phpstan.neon.dist、psalm.xml说明规则作者把「分析配置」也纳入了 Agent 的监控范围——当这些文件被改动时同样应触发 PHP 相关检查。3.3 定向测试PHPUnit / PestPHPUnit / Pest: Run targeted tests for touched files or modules when edits affect behavior.当编辑影响行为时应针对被改动文件或所属模块运行定向测试而不是全量跑测试套件——这是控制 Agent 工作循环耗时的重要策略。测试框架的选择遵循 rules/php/testing.md 的约定PHPUnit 为默认框架若项目已配置 Pest则新测试优先使用 Pest且避免混用两套框架。常用命令vendor/bin/phpunit --filterTargetTest --coverage-text # PHPUnit 定向测试 # 或 vendor/bin/pest --filterTargetTest --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 \$dstream_get_contents(STDIN);$ijson_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 \$dstream_get_contents(STDIN);$ijson_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等字段并必须将原始数据回写到 stdoutmatcher 匹配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.logPHP 版本只需把扫描目标换成上述四个 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避免在控制器/视图中手工拼接 SQLORM 批量赋值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_ENABLEDtrue # 运行档位minimal | standard | strict默认 standard export ECC_HOOK_PROFILEstandard # 按 ID 禁用特定钩子逗号分隔 export ECC_DISABLED_HOOKSpre:bash:tmux-reminder,post:edit:typecheck # 禁用 GateGuard仅限搭建或恢复阶段 export ECC_GATEGUARDoff三个档位的语义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 工程质量闭环。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考