ECC PHP 编码风格指南PSR-12、strict_types 与不可变 DTO 的工程实践【免费下载链接】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 仓库中的 PHP 编码风格规则 为骨架结合同目录下的 patterns、testing、security、hooks 以及 通用层规则 展开为 PHP 开发者提供一套可直接落地到日常开发与 AI 辅助编码流程中的代码质量标准。导读ECCThe agent harness performance optimization system为 Claude Code、Codex、Opencode、Cursor 等 AI 编程环境提供了分层的规则体系其中rules/php/目录面向 PHP 项目定义了从编码风格、架构模式到测试与安全的完整规范。本文聚焦其中的PHP 编码风格规则讲解 PSR-12 格式规范、strict_types严格类型模式、不可变 DTO 设计以及 PHP-CS-Fixer / Laravel Pint / PHPStan / Psalm 的工程化组合方案。读完本文你将能够为 PHP 项目建立一套格式化工具 静态分析 AI 规则约束三合一的代码质量闭环。ECC 规则体系通用层与 PHP 特定层的分层设计在深入编码风格之前先理解该规则在 ECC 中的位置。根据 rules/README.md规则被组织为common 通用层 语言特定目录的两层结构rules/ ├── common/ # 语言无关的通用原则必装 │ ├── coding-style.md │ ├── git-workflow.md │ ├── testing.md │ ├── performance.md │ ├── patterns.md │ ├── hooks.md │ ├── agents.md │ └── security.md └── php/ # PHP 特定规则集 ├── coding-style.md ├── patterns.md ├── testing.md ├── security.md └── hooks.mdrules/php/coding-style.md文件头声明了其作用范围paths: - **/*.php - **/composer.json即该规则会对仓库中所有 PHP 源文件与composer.json生效。文件首行明确写道This file extends common/coding-style.md with PHP specific content说明它是 通用编码风格规则 的 PHP 特化扩展。这种分层设计的优先级遵循语言特定覆盖通用的原则rules/common/定义所有项目通用的默认值rules/php/在语言习惯不同处覆盖这些默认值。标准PSR-12 与严格类型模式PHP 特定规则的第一节Standard提出了三条硬性要求遵循 PSR-12 格式与命名约定PSR-12 是 PHP-FIG 发布的扩展编码风格规范覆盖缩进、命名空间、use语句排序、类与方法声明格式、控制结构写法等它也是 PSR-1 与 PSR-2 的现代替代是当前 PHP 生态事实上的行业基线。应用代码中优先使用declare(strict_types1);启用严格类型模式后函数与方法调用时的标量实参将进行严格类型校验类型不匹配会直接抛出TypeError而不是静默进行隐式转换——这能显著减少因1与 1 混用导致的隐蔽缺陷。新代码允许的范围内处处使用标量类型提示、返回类型与类型化属性即参数int $id、返回: User、属性private int $count这类显式类型声明让类型成为 API 契约的一部分。结合 通用层 coding-style 规则 的命名约定变量/函数用描述性camelCase、布尔值优先is/has/should/can前缀、常量用UPPER_SNAKE_CASEPHP 侧的落地示例为?php declare(strict_types1); namespace App\Order; final class Order { public function __construct( private readonly int $id, private readonly string $status, private readonly bool $isPaid, // 布尔命名遵循 is 前缀 ) {} }说明readonly属性为 PHP 8.1 特性declare(strict_types1)为 PHP 7 特性落地时请以项目实际运行的 PHP 版本为前提。不可变性服务边界的 DTO 与值对象Immutability 是通用层规则中标记为CRITICAL的原则永远创建新对象绝不原地修改已有对象。通用层给出了伪代码对照// 伪代码 错误 modify(original, field, value) → 原地修改 original 正确 update(original, field, value) → 返回带变更的新副本其理由是不可变数据避免隐藏的副作用让调试更容易并支持安全的并发访问。PHP 特定规则在此基础上给出了三条落地策略跨越服务边界的数据优先使用不可变 DTO 与值对象DTOData Transfer Object用于承载请求、命令与外部 API 载荷值对象用于金额、标识符、日期区间等有约束的概念。相关模式详见 rules/php/patterns.md 中的 DTOs and Value Objects 一节。请求/响应载荷尽可能使用readonly属性或不可变构造器构造时一次性注入全部数据之后不可变更。简单映射用数组业务关键结构升级为显式类数组适合松散的 key-value 映射但一旦结构承载业务语义如订单状态机、价格计算就必须提炼为带类型与约束的类。例如一个请求 DTO 的推荐写法?php declare(strict_types1); namespace App\Http\Payload; final class CreateOrderRequest { /** * param arrayint, LineItem $lineItems */ public function __construct( public readonly string $customerId, public readonly array $lineItems, public readonly ?string $couponCode null, ) {} }该文件还强调将框架/请求输入在到达领域逻辑之前转换为已验证的 DTO见下文错误处理一节这与 patterns.md 中用 DTO 替代形状繁重的关联数组的建议互为表里。格式化与静态分析工具链的工程化组合Formatting 一节明确了 PHP 生态的工具选型与组织方式格式化使用PHP-CS-Fixer或Laravel PintPint 本质上是基于 PHP-CS-Fixer 的 Laravel 官方封装零配置开箱即用Laravel 项目首选。静态分析使用PHPStan或Psalm。两者都能在运行前发现类型错误、未定义变量、死代码等隐患PHPStan 以渐进式 level0–9著称Psalm 则内置了污点分析等安全相关能力。Composer 脚本入库将上述命令写入composer.json的scripts段并提交到仓库确保本地与 CI 执行完全相同的命令避免本地能过、CI 挂掉的漂移问题。推荐的composer.json配置{ scripts: { format: vendor/bin/pint, format:test: vendor/bin/pint --test, analyse: vendor/bin/phpstan analyse --memory-limit1G, quality: [ format:test, analyse, test ] }, require-dev: { laravel/pint: ^1.0, phpstan/phpstan: ^1.0 } }使用方式本地运行composer format自动修复格式composer quality在提交前一次性跑完格式检查、静态分析与测试CI 中执行同样的composer quality即可。导入规范use 语句与全局命名空间Imports 一节规定了命名空间的使用纪律为所有引用的类、接口、trait 添加use语句避免每次使用都写完整限定名FQCN提升可读性并方便 IDE 跳转。除非项目明确偏好完全限定名否则避免依赖全局命名空间即不要依赖\DateTime这类隐式全局解析而是在文件顶部显式use DateTime;。这样做可以让依赖关系一目了然也便于静态分析与自动重构。错误处理异常优先拒绝隐藏错误通道Error Handling 一节与 通用层规则 的 Error Handling 原则每一层显式处理错误、绝不静默吞掉错误一脉相承PHP 侧的落地点有两个异常状态抛异常新代码避免用返回false/null作为隐藏错误通道用返回值承载失败信息会迫使调用方逐层检查返回值极易漏判抛出DomainException、InvalidArgumentException等类型化异常可以让错误沿调用栈自然传播并统一处理。框架/请求输入在到达领域逻辑前转换为已验证的 DTO即边界处校验如 LaravelFormRequest、Symfony Validator校验通过后再构建 DTO 传入领域层保证领域逻辑只处理可信数据。这一点与 security.md 中在框架边界校验请求输入的要求完全一致。与同目录规则的协同patterns、testing、security、hooksrules/php/是一个整体编码风格规则与其余四份文件互相印证patterns.md要求瘦控制器 显式服务层控制器只负责传输、鉴权、校验、序列化与状态码业务规则下沉到易于测试的应用/领域服务依赖通过构造器注入接口或窄服务契约避免服务定位器式查找将第三方 SDK 包在小型适配器后让代码库依赖你的契约而非供应商契约。testing.md默认测试框架为PHPUnit若项目配置了Pest则优先 Pest 且不混用运行vendor/bin/phpunit --coverage-text或vendor/bin/pest --coverage查看覆盖率CI 中优先使用 pcov 或 Xdebug 并固化覆盖率阈值将快速单元测试与框架/数据库集成测试分离HTTP/控制器测试只关注传输与校验业务规则放入服务层测试。security.md输出在模板中默认转义所有动态查询使用预处理语句PDO、Doctrine、Eloquent 查询构造器秘密从环境变量或密钥管理器加载CI 中运行composer audit审计依赖密码存储使用password_hash()/password_verify()认证与权限变更后重新生成会话标识对状态变更请求强制 CSRF 防护。hooks.md面向 AI 编码助手配置~/.claude/settings.json中的 PostToolUse Hooks——Pint / PHP-CS-Fixer 自动格式化编辑过的.php文件、PHPStan / Psalm 在类型化代码库中编辑后运行静态分析、PHPUnit / Pest 在行为变更时运行针对性测试同时警告编辑后残留的var_dump、dd、dump、die()以及新增的裸 SQL 或禁用 CSRF/会话保护的改动。编码风格中的格式化工具 静态分析与 hooks 规则中的AI 自动执行格式化与静态分析正好形成人工与自动化双保险。安装与使用让规则进入你的 PHP 项目根据 rules/README.md将 PHP 规则集安装到 AI 编码环境有两种方式方式一安装脚本推荐./install.sh php # 同时安装多个语言规则集 ./install.sh php typescript方式二手动安装到 ECC 规则命名空间# 创建 ECC 规则命名空间一次性 mkdir -p ~/.claude/rules/ecc # 安装通用规则所有项目必需 cp -r rules/common ~/.claude/rules/ecc/ # 安装 PHP 特定规则 cp -r rules/php ~/.claude/rules/ecc/注意必须整目录复制切勿用/*展开。common 与语言目录存在同名文件如coding-style.md扁平化复制会导致语言文件覆盖通用规则并破坏语言文件中对../common/的相对引用。对于项目内规则可在项目根目录使用相同命名空间mkdir -p .claude/rules/ecc后执行同样的复制操作。质量检查清单最终将编码风格规则落到提交前自检可对照 通用层 coding-style 规则 末尾的质量清单并叠加 PHP 特定项代码可读且命名良好PSR-12camelCase 变量is/has/can布尔前缀函数保持短小通用层建议 50 行文件聚焦单一职责通用层建议 200–400 行为典型800 行为软上限无过深嵌套4 层时改用提前返回无魔法数字使用具名常量无硬编码值使用常量或配置无原地修改遵循不可变模式应用代码声明declare(strict_types1);PHP 特定参数、返回类型、类型化属性齐全PHP 特定服务边界数据为不可变 DTO / 值对象PHP 特定composer format与composer analyse本地通过PHP 特定所有引用的类 / 接口 / trait 都有use语句PHP 特定更广泛的服务层/仓储层分层指导可进一步参考 backend-patterns 技能Laravel 项目的架构细节可参考 laravel-patterns、laravel-security 与 laravel-tdd 等技能文档。【免费下载链接】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），仅供参考 ECC PHP 编码风格指南：PSR-12、strict_types 与不可变 DTO 的工程实践
ECC PHP 编码风格指南PSR-12、strict_types 与不可变 DTO 的工程实践【免费下载链接】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 仓库中的 PHP 编码风格规则 为骨架结合同目录下的 patterns、testing、security、hooks 以及 通用层规则 展开为 PHP 开发者提供一套可直接落地到日常开发与 AI 辅助编码流程中的代码质量标准。导读ECCThe agent harness performance optimization system为 Claude Code、Codex、Opencode、Cursor 等 AI 编程环境提供了分层的规则体系其中rules/php/目录面向 PHP 项目定义了从编码风格、架构模式到测试与安全的完整规范。本文聚焦其中的PHP 编码风格规则讲解 PSR-12 格式规范、strict_types严格类型模式、不可变 DTO 设计以及 PHP-CS-Fixer / Laravel Pint / PHPStan / Psalm 的工程化组合方案。读完本文你将能够为 PHP 项目建立一套格式化工具 静态分析 AI 规则约束三合一的代码质量闭环。ECC 规则体系通用层与 PHP 特定层的分层设计在深入编码风格之前先理解该规则在 ECC 中的位置。根据 rules/README.md规则被组织为common 通用层 语言特定目录的两层结构rules/ ├── common/ # 语言无关的通用原则必装 │ ├── coding-style.md │ ├── git-workflow.md │ ├── testing.md │ ├── performance.md │ ├── patterns.md │ ├── hooks.md │ ├── agents.md │ └── security.md └── php/ # PHP 特定规则集 ├── coding-style.md ├── patterns.md ├── testing.md ├── security.md └── hooks.mdrules/php/coding-style.md文件头声明了其作用范围paths: - **/*.php - **/composer.json即该规则会对仓库中所有 PHP 源文件与composer.json生效。文件首行明确写道This file extends common/coding-style.md with PHP specific content说明它是 通用编码风格规则 的 PHP 特化扩展。这种分层设计的优先级遵循语言特定覆盖通用的原则rules/common/定义所有项目通用的默认值rules/php/在语言习惯不同处覆盖这些默认值。标准PSR-12 与严格类型模式PHP 特定规则的第一节Standard提出了三条硬性要求遵循 PSR-12 格式与命名约定PSR-12 是 PHP-FIG 发布的扩展编码风格规范覆盖缩进、命名空间、use语句排序、类与方法声明格式、控制结构写法等它也是 PSR-1 与 PSR-2 的现代替代是当前 PHP 生态事实上的行业基线。应用代码中优先使用declare(strict_types1);启用严格类型模式后函数与方法调用时的标量实参将进行严格类型校验类型不匹配会直接抛出TypeError而不是静默进行隐式转换——这能显著减少因1与 1 混用导致的隐蔽缺陷。新代码允许的范围内处处使用标量类型提示、返回类型与类型化属性即参数int $id、返回: User、属性private int $count这类显式类型声明让类型成为 API 契约的一部分。结合 通用层 coding-style 规则 的命名约定变量/函数用描述性camelCase、布尔值优先is/has/should/can前缀、常量用UPPER_SNAKE_CASEPHP 侧的落地示例为?php declare(strict_types1); namespace App\Order; final class Order { public function __construct( private readonly int $id, private readonly string $status, private readonly bool $isPaid, // 布尔命名遵循 is 前缀 ) {} }说明readonly属性为 PHP 8.1 特性declare(strict_types1)为 PHP 7 特性落地时请以项目实际运行的 PHP 版本为前提。不可变性服务边界的 DTO 与值对象Immutability 是通用层规则中标记为CRITICAL的原则永远创建新对象绝不原地修改已有对象。通用层给出了伪代码对照// 伪代码 错误 modify(original, field, value) → 原地修改 original 正确 update(original, field, value) → 返回带变更的新副本其理由是不可变数据避免隐藏的副作用让调试更容易并支持安全的并发访问。PHP 特定规则在此基础上给出了三条落地策略跨越服务边界的数据优先使用不可变 DTO 与值对象DTOData Transfer Object用于承载请求、命令与外部 API 载荷值对象用于金额、标识符、日期区间等有约束的概念。相关模式详见 rules/php/patterns.md 中的 DTOs and Value Objects 一节。请求/响应载荷尽可能使用readonly属性或不可变构造器构造时一次性注入全部数据之后不可变更。简单映射用数组业务关键结构升级为显式类数组适合松散的 key-value 映射但一旦结构承载业务语义如订单状态机、价格计算就必须提炼为带类型与约束的类。例如一个请求 DTO 的推荐写法?php declare(strict_types1); namespace App\Http\Payload; final class CreateOrderRequest { /** * param arrayint, LineItem $lineItems */ public function __construct( public readonly string $customerId, public readonly array $lineItems, public readonly ?string $couponCode null, ) {} }该文件还强调将框架/请求输入在到达领域逻辑之前转换为已验证的 DTO见下文错误处理一节这与 patterns.md 中用 DTO 替代形状繁重的关联数组的建议互为表里。格式化与静态分析工具链的工程化组合Formatting 一节明确了 PHP 生态的工具选型与组织方式格式化使用PHP-CS-Fixer或Laravel PintPint 本质上是基于 PHP-CS-Fixer 的 Laravel 官方封装零配置开箱即用Laravel 项目首选。静态分析使用PHPStan或Psalm。两者都能在运行前发现类型错误、未定义变量、死代码等隐患PHPStan 以渐进式 level0–9著称Psalm 则内置了污点分析等安全相关能力。Composer 脚本入库将上述命令写入composer.json的scripts段并提交到仓库确保本地与 CI 执行完全相同的命令避免本地能过、CI 挂掉的漂移问题。推荐的composer.json配置{ scripts: { format: vendor/bin/pint, format:test: vendor/bin/pint --test, analyse: vendor/bin/phpstan analyse --memory-limit1G, quality: [ format:test, analyse, test ] }, require-dev: { laravel/pint: ^1.0, phpstan/phpstan: ^1.0 } }使用方式本地运行composer format自动修复格式composer quality在提交前一次性跑完格式检查、静态分析与测试CI 中执行同样的composer quality即可。导入规范use 语句与全局命名空间Imports 一节规定了命名空间的使用纪律为所有引用的类、接口、trait 添加use语句避免每次使用都写完整限定名FQCN提升可读性并方便 IDE 跳转。除非项目明确偏好完全限定名否则避免依赖全局命名空间即不要依赖\DateTime这类隐式全局解析而是在文件顶部显式use DateTime;。这样做可以让依赖关系一目了然也便于静态分析与自动重构。错误处理异常优先拒绝隐藏错误通道Error Handling 一节与 通用层规则 的 Error Handling 原则每一层显式处理错误、绝不静默吞掉错误一脉相承PHP 侧的落地点有两个异常状态抛异常新代码避免用返回false/null作为隐藏错误通道用返回值承载失败信息会迫使调用方逐层检查返回值极易漏判抛出DomainException、InvalidArgumentException等类型化异常可以让错误沿调用栈自然传播并统一处理。框架/请求输入在到达领域逻辑前转换为已验证的 DTO即边界处校验如 LaravelFormRequest、Symfony Validator校验通过后再构建 DTO 传入领域层保证领域逻辑只处理可信数据。这一点与 security.md 中在框架边界校验请求输入的要求完全一致。与同目录规则的协同patterns、testing、security、hooksrules/php/是一个整体编码风格规则与其余四份文件互相印证patterns.md要求瘦控制器 显式服务层控制器只负责传输、鉴权、校验、序列化与状态码业务规则下沉到易于测试的应用/领域服务依赖通过构造器注入接口或窄服务契约避免服务定位器式查找将第三方 SDK 包在小型适配器后让代码库依赖你的契约而非供应商契约。testing.md默认测试框架为PHPUnit若项目配置了Pest则优先 Pest 且不混用运行vendor/bin/phpunit --coverage-text或vendor/bin/pest --coverage查看覆盖率CI 中优先使用 pcov 或 Xdebug 并固化覆盖率阈值将快速单元测试与框架/数据库集成测试分离HTTP/控制器测试只关注传输与校验业务规则放入服务层测试。security.md输出在模板中默认转义所有动态查询使用预处理语句PDO、Doctrine、Eloquent 查询构造器秘密从环境变量或密钥管理器加载CI 中运行composer audit审计依赖密码存储使用password_hash()/password_verify()认证与权限变更后重新生成会话标识对状态变更请求强制 CSRF 防护。hooks.md面向 AI 编码助手配置~/.claude/settings.json中的 PostToolUse Hooks——Pint / PHP-CS-Fixer 自动格式化编辑过的.php文件、PHPStan / Psalm 在类型化代码库中编辑后运行静态分析、PHPUnit / Pest 在行为变更时运行针对性测试同时警告编辑后残留的var_dump、dd、dump、die()以及新增的裸 SQL 或禁用 CSRF/会话保护的改动。编码风格中的格式化工具 静态分析与 hooks 规则中的AI 自动执行格式化与静态分析正好形成人工与自动化双保险。安装与使用让规则进入你的 PHP 项目根据 rules/README.md将 PHP 规则集安装到 AI 编码环境有两种方式方式一安装脚本推荐./install.sh php # 同时安装多个语言规则集 ./install.sh php typescript方式二手动安装到 ECC 规则命名空间# 创建 ECC 规则命名空间一次性 mkdir -p ~/.claude/rules/ecc # 安装通用规则所有项目必需 cp -r rules/common ~/.claude/rules/ecc/ # 安装 PHP 特定规则 cp -r rules/php ~/.claude/rules/ecc/注意必须整目录复制切勿用/*展开。common 与语言目录存在同名文件如coding-style.md扁平化复制会导致语言文件覆盖通用规则并破坏语言文件中对../common/的相对引用。对于项目内规则可在项目根目录使用相同命名空间mkdir -p .claude/rules/ecc后执行同样的复制操作。质量检查清单最终将编码风格规则落到提交前自检可对照 通用层 coding-style 规则 末尾的质量清单并叠加 PHP 特定项代码可读且命名良好PSR-12camelCase 变量is/has/can布尔前缀函数保持短小通用层建议 50 行文件聚焦单一职责通用层建议 200–400 行为典型800 行为软上限无过深嵌套4 层时改用提前返回无魔法数字使用具名常量无硬编码值使用常量或配置无原地修改遵循不可变模式应用代码声明declare(strict_types1);PHP 特定参数、返回类型、类型化属性齐全PHP 特定服务边界数据为不可变 DTO / 值对象PHP 特定composer format与composer analyse本地通过PHP 特定所有引用的类 / 接口 / trait 都有use语句PHP 特定更广泛的服务层/仓储层分层指导可进一步参考 backend-patterns 技能Laravel 项目的架构细节可参考 laravel-patterns、laravel-security 与 laravel-tdd 等技能文档。【免费下载链接】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），仅供参考