ECC PHP Coding Style 规则实践PSR-12、strict_types、不可变 DTO 与 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本文以 php-coding-style.md 这份 Cursor 规则文件为主体逐条拆解 ECCThe agent harness performance optimization system中 PHP 编码风格规则的三大核心板块——编码标准、不可变性与格式化工具链并结合仓库中的同名 Claude Code 规则、通用基础规则与 Cursor 安装适配器源码说明这条规则如何被触发、如何生效以及它背后的分层设计。读完你可以掌握ECC 规则文件的 frontmatter 触发机制、PSR-12 与严格类型在 PHP 项目中的落地要点以及如何用 PHP-CS-Fixer/Pint PHPStan/Psalm 搭起一套本地与 CI 一致的格式和静态分析流水线。规则文件定位与 frontmatter 机制php-coding-style.md 是 ECC 为 Cursor harness 适配的 PHP 编码风格规则位于仓库根目录的.cursor/rules/目录下。文件开头的 YAML frontmatter 决定了它在 Cursor 中的触发方式description: PHP coding style extending common rules globs: [**/*.php, **/composer.json] alwaysApply: false字段取值作用descriptionPHP coding style extending common rules向 Agent 声明该规则的主题即扩展通用编码风格规则并加入 PHP 专属内容globs**/*.php、**/composer.json文件匹配模式。只有当会话上下文涉及任意.php源码文件或composer.json时该规则才会被注入alwaysApplyfalse不全局生效按 glob 条件激活与之对照同目录下的 common-coding-style.md 设置了alwaysApply: true作为语言无关的通用编码风格基线。也就是说ECC 的规则体系是通用基线alwaysApply 语言特化规则globs 触发的两层结构PHP 规则文件自己也明确声明了这一点——This file extends the common coding style rule with PHP specific content.这里有一个值得注意的细节仓库同时维护了同一规则在不同 harness 下的两份表面。Cursor 变体在 .cursor/rules/php-coding-style.mdClaude Code 安装用的完整变体在 rules/php/coding-style.md后者 frontmatter 使用paths字段而非globs并多出 Imports、Error Handling 等章节。从源码结构看这种同源双份的布局正是由 Cursor 安装适配器 cursor-project.js 驱动的——该适配器以.cursor为目标根段rootSegments: [.cursor]负责把 ECC 规则模块映射进宿主项目的 Cursor 目录结构。编码标准PSR-12 与严格类型原文档的 Standards 板块给出三条硬性标准这也是整份规则的基础约束遵循 PSR-12格式与命名约定一律以 PSR-12 为准不做项目自定义偏离优先使用declare(strict_types1);应用代码中默认开启严格类型模式禁止依赖 PHP 的弱类型隐式转换全量类型标注凡新代码允许的地方一律使用标量类型提示scalar type hints、返回类型return types和带类型的属性typed properties。strict_types的意义在于把类型契约从文档约定变成运行时强制开启后传入标量类型不匹配的参数会直接抛出TypeError而不是被静默转换。一个最简示意标准 PHP 8.x 写法用于说明规则意图?php declare(strict_types1); final class OrderTotal { public function __construct(private readonly int $amountCents) {} public function withTax(int $taxCents): self { // 不可变更新返回新实例不修改 $this return new self($this-amountCents $taxCents); } }不可变性DTO、readonly 与数组还是类的判定Immutability 板块是这份规则的技术核心三条要求分别对应数据在系统边界、载荷结构和内部组织的三个层面跨服务边界的数据优先使用不可变 DTO 与值对象。请求体、响应体、外部 API 载荷等跨越服务边界的数据结构不应是散装的关联数组而应是显式的、不可变的对象尽可能使用readonly属性或不可变构造函数处理请求/响应载荷。PHP 8.1 的readonly属性及 8.2 的readonly class在语言层面保证属性只能在构造函数中赋值一次与不可变 DTO的目标天然契合数组只留给简单映射。简单 map如枚举表、配置字典保持数组即可一旦某个结构承载业务关键语义就应提升promote为显式类。这条 PHP 规则并不是凭空设立的它是对通用基线规则中最高优先级原则的语言化落地。在 common-coding-style.md 中Immutability 被标记为 CRITICAL并给出伪代码对比WRONG: modify(original, field, value) → changes original in-place CORRECT: update(original, field, value) → returns new copy with change其理由是不可变数据消除隐藏副作用、简化调试、并支持并发场景下的安全共享。PHP 规则把这一通用原则翻译成具体手段readonly属性、不可变构造函数这正是 rules/README.md 所描述的分层覆盖模式详见下文规则分层一节。同一主题下的 php-patterns.md 进一步给出了组织层约束把形状繁重的关联数组替换为请求、命令和外部 API 载荷的 DTO对金额、标识符、受限概念使用值对象控制器保持薄业务规则下沉到便于脱离 HTTP 引导进行单元测试的应用/领域服务。格式与静态分析工具链Formatting 板块指定了两类工具的组合目的指定工具格式化PHP-CS-Fixer或Laravel Pint二选一按项目栈定静态分析PHPStan或Psalm二选一按项目栈定选择逻辑很清晰Laravel 项目用 Pint与 Laravel 生态深度集成、配置极简非 Laravel 的通用 PHP 项目用 PHP-CS-Fixer配置能力更强PHPStan 与 Psalm 都是重型静态分析器任选其一即可不必重复接入。Claude Code 侧的完整版规则 rules/php/coding-style.md 在此板块上还多出一条对 CI 落地至关重要的要求把 Composer scripts 检查入库保证本地与 CI 执行的是同一组命令。例如在composer.json中固化{ scripts: { format: pint, static: phpstan analyse } }这样开发者本地composer format/composer static与 CI 流水线跑的完全一致避免本地通过、CI 失败的工具版本漂移。该文件还补充了 Cursor 变体未涵盖的另外两条标准Imports所有被引用的类、接口、trait 都必须显式use除非项目明确偏好全限定名否则不要依赖全局命名空间Error Handling异常状态应抛异常避免在新代码里用返回false/null作为隐藏的错误通道框架/请求输入必须先转换成经过校验的 DTO再进入领域逻辑与上文 Immutability 板块首条形成闭环。该文件末尾还指向前置技能backend-patterns对应 skills/backend-patterns/作为服务/仓储分层指导的延伸阅读体现了 ECC Rules 告诉你做什么、Skills 告诉你怎么做 的分工。规则体系之外PHP 工具链还会通过 hooks 自动执行。php-hooks.md 描述了 PostToolUse 阶段的行为Agent 每次编辑.php文件后自动触发 Pint / PHP-CS-Fixer 格式化在类型化代码库中运行 PHPStan / Psalm 静态分析当编辑影响行为时运行 PHPUnit / Pest 的定向测试。同时设有两条告警编辑后的文件中残留var_dump、dd、dump、die()时告警编辑引入裸 SQL 或关闭 CSRF/会话保护时告警。其 glob 比编码风格规则多匹配了phpstan.neon(.dist)与psalm.xml保证配置工具文件被改动时同样触发检查。规则分层、优先级与安装方式rules/README.md 完整定义了 ECC 规则库的组织方式理解它是理解本文件如何生效的关键目录结构rules/common/存放语言无关原则coding-style、git-workflow、testing、performance、patterns、hooks、agents、security语言目录rules/php/、rules/python/、rules/typescript/等各自提供 5 个文件coding-style、hooks、patterns、security、testing每个语言文件都以 This file extends common/xxx.md with … specific content 开头指回对应的 common 版本优先级语言特定规则与通用规则冲突时语言特定规则优先specific overrides general遵循类似 CSS 选择器优先级的分层覆盖模式。PHP 规则对不可变性原则的语言化翻译就是这一机制的实例——common 层要求永不原地修改PHP 层给出了readonly属性与不可变构造函数这两个具体落点Cursor 安装路径按 README.md 的 Cursor 支持说明安装命令为./install.sh --target cursor python golang swift php # 或 Windows PowerShell .\install.ps1 --target cursor typescriptREADME 给出的 Cursor 组件清单中规则部分共 34 条9 条 commonalwaysApply 25 条语言特定规则覆盖 TypeScript、Python、Go、Swift、PHP与.cursor/rules/目录下的文件构成一致。手动安装时的注意事项来自 rules/README.md整目录拷贝、不要用/*摊平——common 与语言目录存在同名文件摊平后语言文件会覆盖通用规则同时打断语言文件中对../common/的相对引用。规则要点速查板块规则要点落地工具/手段触发机制仅当涉及**/*.php、**/composer.json时激活frontmatterglobsalwaysApply: false标准PSR-12 格式与命名PHP-CS-Fixer / Laravel Pint 强制标准declare(strict_types1)应用于应用代码静态分析器可检测缺失标准标量类型提示、返回类型、类型属性全覆盖PHPStan / Psalm 检查不可变性跨服务边界用不可变 DTO / 值对象readonly属性、不可变构造函数不可变性数组仅作简单映射业务关键结构提升为类代码评审 静态分析格式Composer scripts 入库本地与 CI 同命令composer.jsonscripts自动执行编辑后自动格式化、静态分析、定向测试PostToolUse hooksphp-hooks.md告警残留调试语句、裸 SQL、关闭 CSRFhooks 告警小结php-coding-style.md 虽然篇幅精炼但完整地覆盖了一个 PHP 项目的质量基线以 PSR-12 和strict_types确立编码标准以readonlyDTO 落实不可变性这一通用核心原则以 PHP-CS-Fixer/Pint PHPStan/Psalm 构成格式化与静态分析双保险。它不是一个孤立的清单文件而是 ECC 分层规则体系common 基线 → 语言特化覆盖 → hooks 自动执行 → 多 harness 适配安装中的一环同样的 PHP 规则在 Claude Code 侧有内容更完整的 rules/php/coding-style.md配套的 php-patterns.md、php-security.md、php-testing.md 则分别补齐了分层设计、安全与测试约束。在 PHP 项目中启用 ECC 后这套规则会随.php文件的编辑自动进入 Agent 上下文使 AI 生成的代码默认遵循团队约定的编码风格。【免费下载链接】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），仅供参考