PHPackages                             fatbit/form-request-param - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. fatbit/form-request-param

ActiveSdk[Utility & Helpers](/categories/utility)

fatbit/form-request-param
=========================

this is hyperf form request param

0.3.2(4mo ago)267MITPHPPHP ^8.1

Since Feb 23Pushed 4mo ago1 watchersCompare

[ Source](https://github.com/duncanxia97/hyperf-form-request-param)[ Packagist](https://packagist.org/packages/fatbit/form-request-param)[ RSS](/packages/fatbit-form-request-param/feed)WikiDiscussions main Synced today

READMEChangelogDependencies (5)Versions (14)Used By (0)

🚀 Form Request Param for Hyperf
===============================

[](#-form-request-param-for-hyperf)

> [Github 地址](https://github.com/duncanxia97/hyperf-form-request-param) | [Gitee 地址 (国内访问)](https://gitee.com/duncanxia/hyperf-form-request-param)

一个强大的 HTTP 请求参数验证器与 `RequestParam` 映射工具。旨在解决控制器层与逻辑层的数据参数转换与验证问题，让你的代码更优雅、更健壮！✨

✨ 主要特性
------

[](#-主要特性)

- 🎯 **自动验证**：基于注解的声明式验证规则，由 `Hyperf` 自动触发。
- 🔄 **`RequestParam` 自动映射**：请求参数自动转换为强类型的 PHP 对象，拒绝弱类型数组地狱。
- 🧩 **嵌套对象支持**：支持无限层级的嵌套 `RequestParam` 验证与转换。
- 📦 **复杂类型兼容**：完美支持 `Union Types` (如 `RequestParam|array`)，智能判断并优先实例化对象。
- ♻️ **复用性强**：支持在控制器方法中自由组合多个 `RequestParam`，灵活应对不同业务场景。
- 📋 **数组处理**：支持对象数组 (`List`) 和关联数组 (`Map`) 的自动转换。
- 🛠 **开箱即用**：提供命令行工具快速生成 RequestParam 类。

📦 下载安装
------

[](#-下载安装)

```
composer require fatbit/form-request-param
```

🚀 快速上手
------

[](#-快速上手)

### 1. 创建 RequestParam 类

[](#1-创建-requestparam-类)

使用命令行工具快速生成：

```
php bin/hyperf gen:request-param User
```

执行后将在 `App\RequestParams` 目录下生成 `UserRequestParam` 类。

### 2. 定义验证规则与属性

[](#2-定义验证规则与属性)

使用 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;
}
```

### 3. 在控制器中使用

[](#3-在控制器中使用)

在控制器方法中直接注入即可自动触发验证。支持**组合复用**多个 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));
    }
}
```

---

💡 高级用法
------

[](#-高级用法)

### 1. 嵌套对象 (Nested objects)

[](#1-嵌套对象-nested-objects)

支持直接引用其他的 `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;
}
```

### 2. 联合类型与智能转换 (Union Types) ⚡️

[](#2-联合类型与智能转换-union-types-️)

完美支持 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
     */
    // 3. 关联数组对象 (Map Mode)：针对特定 Key 转换
    // arrayField 为字符串键名 'company'
    #[FormRequestRule('array', '公司信息')]
    #[FormRequestArrayRule(AddressParam::class, arrayField: 'company')]
    public array $companyInfo; // $companyInfo['company'] 将被转换为 AddressParam 对象。
}
```

### 3. 数组对象列表 (List Mode) 📋

[](#3-数组对象列表-list-mode-)

处理对象数组 `[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;
}
```

### 4. 关联数组对象 (Map Mode) 🗺

[](#4-关联数组对象-map-mode-)

处理特定 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
     */
    #[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

###  Health Score

38

—

LowBetter than 83% of packages

Maintenance74

Regular maintenance activity

Popularity12

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity48

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~72 days

Recently: every ~47 days

Total

11

Last Release

141d ago

Major Versions

0.1.0 → 2.2.x-dev2025-06-15

PHP version history (2 changes)0.1.0PHP ^8.0

0.3.0PHP ^8.1

### Community

Maintainers

![](https://www.gravatar.com/avatar/789a7caaa95f72708611ef8f6f67899ad918e09eba79caff325d8ce6eb6645e5?d=identicon)[duncanxia](/maintainers/duncanxia)

---

Top Contributors

[![duncanxia97](https://avatars.githubusercontent.com/u/42824633?v=4)](https://github.com/duncanxia97 "duncanxia97 (15 commits)")

---

Tags

paramhyperfphp80form-request

### Embed Badge

![Health badge](/badges/fatbit-form-request-param/health.svg)

```
[![Health](https://phpackages.com/badges/fatbit-form-request-param/health.svg)](https://phpackages.com/packages/fatbit-form-request-param)
```

###  Alternatives

[tangwei/dto

php hyperf dto

18138.4k3](/packages/tangwei-dto)[hyperf/di

A DI for Hyperf.

173.0M690](/packages/hyperf-di)[hyperf/crontab

A crontab component for Hyperf.

131.7M77](/packages/hyperf-crontab)[hyperf/watcher

Hot reload watcher for Hyperf

17904.9k31](/packages/hyperf-watcher)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)