Download the PHP package tangwei/dto without Composer

Hyperf DTO

English | 中文

基于 Hyperf 框架的 DTO（数据传输对象）映射和验证库，使用 PHP 8 Attributes 特性，提供优雅的请求参数绑定和验证方案。

✨ 特性

• 🚀 自动映射 — 请求参数自动映射到 PHP DTO 类
• 🎯 类型安全 — 利用 PHP 8.2+ 的类型系统，提供完整的类型提示
• 🔄 递归支持 — 支持数组、嵌套对象、递归结构（最大嵌套深度 100）
• ✅ 数据验证 — 集成 Hyperf 验证器，提供约 90 个验证注解
• 📝 多种参数源 — 支持 Body、Query、FormData、Header 等多种参数来源
• 🎨 代码优雅 — 基于 PHP 8 Attributes，代码简洁易读
• 🔧 易于扩展 — 支持自定义验证规则和响应字段名转换
• 📡 RPC 支持 — 兼容 JSON-RPC（TCP/HTTP）服务的参数验证

📋 环境要求

• PHP >= 8.2
• Hyperf ~3.2
• （可选）hyperf/validation — 数据验证
• （可选）symfony/serializer + symfony/property-access — RPC 对象序列化

📦 安装

安装后组件通过 ConfigProvider 自动注册，无需额外配置。

📖 快速开始

基本使用

1. 创建 DTO 类

2. 在控制器中使用

请求 /user/info?name=tom&age=20 时，$request 会自动填充并验证；验证失败抛出 Hyperf\Validation\ValidationException。

📚 注解说明

参数来源注解

命名空间：Hyperf\DTO\Annotation\Contracts

RequestBody

获取 POST/PUT/PATCH 请求的 Body 参数：

RequestQuery

获取 URL 查询参数（GET 参数）：

RequestFormData

获取表单请求数据（Content-Type: multipart/form-data）：

RequestHeader

获取请求头信息（一个方法中最多只能有一个 RequestHeader 参数）：

Valid

启用验证，必须与参数来源注解一起使用：

组合使用

可以在同一方法中组合使用多种参数来源：

⚠️ 注意：

• 同一参数上 RequestBody、RequestQuery、RequestFormData 互斥，只能标注其一
• 同一方法中 RequestBody 与 RequestFormData 不能同时存在于不同参数上
• 违反以上约束会在服务启动扫描阶段抛出 Hyperf\DTO\Exception\DtoException，提前暴露错误

📝 完整示例

控制器示例

DTO 类示例

简单 DTO

嵌套对象 DTO

嵌套对象会递归映射并递归验证（验证规则取嵌套类自身的注解）：

数组类型 DTO

请求体为 JSON 数组

控制器方法形参声明为 array，配合 @param 注解指定元素类型，可实现 JSON 数组的批量映射与逐项验证：

枚举类型

PHP 8.1+ 的 BackedEnum 可直接作为属性类型，映射时自动按值转换：

自定义字段名

✅ 数据验证

需要先安装 Hyperf 验证器：composer require hyperf/validation

内置验证注解

本库提供 90+ 个验证注解（命名空间 Hyperf\DTO\Annotation\Validation），与 Laravel 验证规则一一对应，常用的包括：

使用示例

基本验证

在控制器中使用 #[Valid] 注解启用验证：

自定义错误消息

每个验证注解的最后一个参数为自定义消息：

使用 Validation 注解

Validation 注解支持 Laravel 风格的验证规则字符串，并可通过 customKey 验证数组元素：

⚠️ 注意：字符串形式的规则按 | 拆分、按 : 提取参数，因此规则本身包含 | 或 : 时（如 regex:/^(a|b)$/、date_format:H:i）会被错误拆分。涉及正则的规则请使用 Regex 专用注解或数组形式。

自定义验证规则

继承 BaseValidation 类即可创建自定义验证规则：

使用自定义验证：

⚙️ 配置

组件无需配置即可工作。如需定制，创建 config/autoload/dto.php（或 api_docs.php）：

⚠️ 注意：scan_cacheable 读取的是顶层配置键。若使用独立的 dto.php 配置文件，请确保该键位于配置根级。

🔧 高级功能

手动映射

脱离 HTTP 请求场景时，可直接使用 Mapper 静态门面：

响应字段名转换

类级转换

全局转换

在配置中设置 responses_global_convert（见上文「配置」章节），类级 #[Dto] 注解优先级更高。

自定义转换

使用 Convert::CUSTOM 前需注册转换闭包（如在 BootApplication 监听器中）：

事件

组件在启动阶段会派发事件，可监听以扩展行为：

RPC 支持

在 JSON-RPC 服务中返回 PHP 对象，需要配置序列化支持。

1. 安装依赖

2. 配置 Aspect

在 config/autoload/aspects.php 中添加：

3. 配置依赖

在 config/autoload/dependencies.php 中添加：

💡 最佳实践

1. DTO 类结构设计

• 为不同的请求类型创建独立的 DTO 类
• 使用有意义的类名，如 CreateUserRequest、UpdateUserRequest
• 将 Request DTO 和 Response DTO 分开存放

2. 验证规则

• 优先使用内置验证注解，保持代码可读性
• 复杂验证使用 Validation 注解
• 通用验证规则封装为自定义注解

3. 错误处理

验证失败会抛出 Hyperf\Validation\ValidationException 异常，可以通过异常处理器统一处理：

4. 生产环境部署

• 设置 scan_cacheable = true，在构建/发布阶段执行一次扫描生成代理文件（runtime/container/proxy/*.dto.proxy.php），运行时直接加载，减少启动开销
• 代理文件按源文件修改时间自动过期重建（scan_cacheable = false 时）

📚 常见问题

Q: 为什么验证没有生效？

A: 请确保：

1. 已安装 hyperf/validation 组件
2. 在控制器方法参数上添加了 #[Valid] 注解
3. DTO 类中的属性添加了验证注解

Q: 如何处理嵌套数组？

A: 使用 PHPDoc 或 ArrayType 注解：

Q: 可以同时使用 RequestBody 和 RequestFormData 吗？

A: 不可以。这两个注解是互斥的，因为它们处理不同的请求类型，启动扫描阶段会抛出 DtoException。

Q: 如何处理文件上传？

A: 使用 RequestFormData 注解，然后通过 $this->request->file() 获取文件。

Q: 嵌套 DTO 的验证规则如何生效？

A: 外层 DTO 验证通过后，组件会递归验证嵌套对象（含对象数组的每个元素），规则取嵌套类属性上的验证注解。嵌套字段为空时跳过递归验证，如需强制必填请在外层属性上加 #[Required]。

Q: DTO 嵌套层级有限制吗？

A: 有，最大嵌套深度为 100，防止循环引用导致无限递归，超限会抛出 DtoException。

🔗 相关链接

• Hyperf 官方文档
• Hyperf Validation
• PHP Attributes