一个强大的 HTTP 请求参数验证器与 RequestParam 映射工具。旨在解决控制器层与逻辑层的数据参数转换与验证问题，让你的代码更优雅、更健壮！✨
- 🎯 自动验证：基于注解的声明式验证规则，由
Hyperf自动触发。 - 🔄
RequestParam自动映射：请求参数自动转换为强类型的 PHP 对象，拒绝弱类型数组地狱。 - 🧩 嵌套对象支持：支持无限层级的嵌套
RequestParam验证与转换。 - 📦 复杂类型兼容：完美支持
Union Types(如RequestParam|array)，智能判断并优先实例化对象。 - ♻️ 复用性强：支持在控制器方法中自由组合多个
RequestParam，灵活应对不同业务场景。 - 📋 数组处理：支持对象数组 (
List<RequestParam>) 和关联数组 (Map<string, RequestParam>) 的自动转换。 - 🛠 开箱即用：提供命令行工具快速生成 RequestParam 类。
composer require fatbit/form-request-param使用命令行工具快速生成：
php bin/hyperf gen:request-param User执行后将在 App\RequestParams 目录下生成 UserRequestParam 类。
使用 PHP 8.1+ 注解定义参数规则：
namespace App\RequestParams;
use Fatbit\FormRequestParam\Abstracts\AbstractFormRequestParam;
use Fatbit\FormRequestParam\Annotations\FormRequestRule;
use Fatbit\FormRequestParam\Annotations\FormRequestArrayRule;
class UserRequestParam extends AbstractFormRequestParam
{
#[FormRequestRule('required|string|max:255', '姓名')]
public string $name;
#[FormRequestRule('required|integer|in:1,2', '性别')]
public int $sex;
// 支持别名映射：前端传 'username' -> 映射到后端 $account
#[FormRequestRule('required|string|max:255', '账号', 'username')]
public string $account;
// 简单数组验证
#[FormRequestRule('required|array', '标签')]
#[FormRequestArrayRule('*', 'required|int|gt:0', '标签Id')]
public array $tags;
}在控制器方法中直接注入即可自动触发验证。支持组合复用多个 RequestParam，例如将通用的 ID 验证提取为 IdRequestParam。
namespace App\Controller;
use App\RequestParams\UserRequestParam;
use App\RequestParams\IdRequestParam;
class UserController extends AbstractController
{
/**
* 创建用户
* 自动验证 UserRequestParam
*/
public function create(UserRequestParam $requestParam)
{
// 验证通过后，$requestParam 已经自动填充好数据
// 直接传入 Service 层，业务逻辑无需再处理参数验证
return $this->success($this->service->create($requestParam));
}
/**
* 修改用户
* ✨ 支持复用：同时注入多个 RequestParam
* 自动验证所有注入的参数对象，任何一个验证失败都会终止请求
*/
public function modify(IdRequestParam $idParam, UserRequestParam $userParam)
{
// $idParam 负责验证 ID 存在性与格式
// $userParam 负责验证用户信息的合法性
return $this->success($this->service->modify($idParam->id, $userParam));
}
}支持直接引用其他的 RequestParam 类作为属性，自动递归验证与实例化。
namespace App\RequestParams;
use Fatbit\FormRequestParam\Abstracts\AbstractFormRequestParam;
use Fatbit\FormRequestParam\Annotations\FormRequestRule;
use Fatbit\FormRequestParam\Annotations\FormRequestArrayRule;
class CreateOrderParam extends AbstractFormRequestParam
{
// 自动验证并实例化 UserInfoParam
#[FormRequestRule('required', '用户信息')]
public UserInfoParam $userInfo;
// 支持 Nullable
#[FormRequestRule('nullable', '收货地址')]
public ?AddressParam $address;
}完美支持 PHP 联合类型。当定义为 RequestParam|array 时，系统会优先尝试实例化对象，只有当实例化失败或数据不符合时才回退为数组。
namespace App\RequestParams;
use Fatbit\FormRequestParam\Abstracts\AbstractFormRequestParam;
use Fatbit\FormRequestParam\Annotations\FormRequestRule;
use Fatbit\FormRequestParam\Annotations\FormRequestArrayRule;
class ProductParam extends AbstractFormRequestParam
{
// 优先转换为 SkuParam 对象，如果失败则保留为数组
#[FormRequestRule('required', 'SKU信息')]
public SkuParam|array $skuInfo;
// 明确指定属性为 array，但在注解中定义转换为 RequestParam
// 此时 propertyType 为 array，但 toVal 指向 RequestParam，会调用 RequestParam->toArray()
// 默认 arrayField 为 false (或者不传)，表示直接转换当前字段
#[FormRequestRule('required|array', '配置信息')]
#[FormRequestArrayRule(ConfigParam::class)]
public array $config;
/**
* @var AddressParam[]
*/
// 2. 对象数组 (List Mode)：验证并转换每个元素为 AddressParam
// 使用 FormRequestArrayRule 并传入类名，arrayField 为 true 代表列表模式
#[FormRequestRule('array', '其他地址列表')]
#[FormRequestArrayRule(AddressParam::class, arrayField: true)]
public array $otherAddresses;
/**
* @var array<string, AddressParam>
*/
// 3. 关联数组对象 (Map Mode)：针对特定 Key 转换
// arrayField 为字符串键名 'company'
#[FormRequestRule('array', '公司信息')]
#[FormRequestArrayRule(AddressParam::class, arrayField: 'company')]
public array $companyInfo; // $companyInfo['company'] 将被转换为 AddressParam 对象。
}处理对象数组 [UserRequestParam, UserRequestParam]。
提供了专用的 FormRequestListArrayRule 注解，语法更简洁。
namespace App\RequestParams;
use Fatbit\FormRequestParam\Abstracts\AbstractFormRequestParam;
use Fatbit\FormRequestParam\Annotations\FormRequestRule;
use Fatbit\FormRequestParam\Annotations\FormRequestListArrayRule;
class BatchCreateParam extends AbstractFormRequestParam
{
/**
* @var UserRequestParam[]
*/
#[FormRequestRule('required|array', '用户列表')]
// 使用 FormRequestListArrayRule，默认数组索引模式
// 等同于 #[FormRequestArrayRule(UserRequestParam::class, arrayField: true)]
#[FormRequestListArrayRule(UserRequestParam::class)]
public array $userList;
}处理特定 Key 的对象转换，例如 {"old": UserRequestParam, "new": UserRequestParam}。
提供了专用的 FormRequestMappingArrayRule 注解，明确指定映射键。
namespace App\RequestParams;
use Fatbit\FormRequestParam\Abstracts\AbstractFormRequestParam;
use Fatbit\FormRequestParam\Annotations\FormRequestRule;
use Fatbit\FormRequestParam\Annotations\FormRequestMappingArrayRule;
class CompareParam extends AbstractFormRequestParam
{
/**
* @var array<string, UserRequestParam>
*/
#[FormRequestRule('array', '对比数据')]
// 映射 old 字段 -> UserRequestParam
#[FormRequestMappingArrayRule(UserRequestParam::class, 'old')]
// 映射 new 字段 -> UserRequestParam
#[FormRequestMappingArrayRule(UserRequestParam::class, 'new')]
// 等同于 #[FormRequestArrayRule(UserRequestParam::class, arrayField: 'new')]
public array $compareData;
}| 命令 | 描述 |
|---|---|
gen:request-param {name} |
快速生成 RequestParam 类文件 |
欢迎提交 Issue 或 Pull Request！
License: MIT