---
paths:
  - "**/*.php"
  - "**/composer.json"
---

# PHP 编码风格

> 此文件在 [common/coding-style.md](../common/coding-style.md) 的基础上扩展了 PHP 相关内容。

## 标准

* 遵循 **PSR-12** 的格式化和命名约定。
* 在应用程序代码中优先使用 `declare(strict_types=1);`。
* 在所有新代码允许的地方使用标量类型提示、返回类型和类型化属性。

## 不可变性

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

## 格式化

* 使用 **PHP-CS-Fixer** 或 **Laravel Pint** 进行格式化。
* 使用 **PHPStan** 或 **Psalm** 进行静态分析。
* 将 Composer 脚本纳入版本控制，以便在本地和 CI 中运行相同的命令。

## 导入

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

## 错误处理

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

## 参考

有关更广泛的服务/仓库分层指导，请参阅技能：`backend-patterns`。