PHP 编码风格¶

此文件使用 PHP 特定内容扩展 common/coding-style.md。

标准¶

• 遵循 PSR-12 的格式和命名规则。
• 在应用代码中优先使用 declare(strict_types=1);。
• 在新代码允许的情况下，在所有地方使用标量类型提示、返回类型和类型化属性。

不可变性¶

• 对于跨越服务边界的数据，优先使用不可变 DTO 和值对象。
• 在可能的情况下，对请求/响应载荷使用 readonly 属性或不可变构造函数。
• 简单映射使用数组；业务关键结构提升为显式类。

格式¶

• 使用 PHP-CS-Fixer 或 Laravel Pint 进行格式化。
• 使用 PHPStan 或 Psalm 进行静态分析。
• 提交 Composer 脚本，确保本地和 CI 中执行相同的命令。

导入¶

• 为所有被引用的类、接口和特性添加 use 语句。
• 除非项目明确偏好完全限定名，否则避免依赖全局命名空间。

错误处理¶

• 对异常状态抛出异常；在新代码中避免将 false/null 作为隐藏错误通道返回。
• 在框架/请求输入到达领域逻辑之前，将其转换为已验证的 DTO。

参考¶

技能：请参见 backend-patterns 中更广泛的服务/仓库分层指导。