README

ThinkPHP 8.1+ 参数校验与 JSON 响应一体化组件包。

Input：类型安全的 HTTP 参数提取器（Post / Get / Combi / Raw），自动触发参数缺失或类型错误的失败响应。
Ret：统一 JSON 响应类，包含 Success / Fail 及常用 HTTP 状态码快捷方法。
CommitMessage\Analyzer：基于 Conventional Commits 规范的提交信息解析与描述生成器。
removeXSS()：基于 HTMLPurifier 的 XSS 清洗助手函数（可选依赖）。

要求 PHP 8.5 及以上。

安装

composer require tuuz/input

ThinkPHP 8 会通过 extra.think.aliases 自动注册门面别名 Input 与 Ret，无需额外配置即可在全局直接使用。

可选依赖（启用高级 XSS 清洗）：

composer require ezyang/htmlpurifier:^4.16

Input：参数提取（Input::）

所有 Post* / Get* 方法签名相同：

(string $name, bool $must_have = true)

$must_have = true：缺失 / 类型不匹配 → 自动 Ret::Fail(400, ...) 输出 JSON 并 exit

方法	返回类型	说明
`Input::Post($name, $must, $xss)`	`string`	POST 字符串
`Input::PostInt($name, $must)`	`int`	POST 整数
`Input::PostFloat($name, $must)`	`float`	POST 浮点数
`Input::PostBool($name, $must)`	`bool`	POST 布尔
`Input::PostDateTime($name, $must)`	`string\|null`	RFC3339 格式时间
`Input::PostJson($name, $must)`	`array`	JSON 字符串 → 数组
`Input::Get($name, $must, $xss)`	`string`	GET 字符串
`Input::GetInt($name, $must)`	`int`	GET 整数
`Input::GetFloat($name, $must)`	`float`	GET 浮点数
`Input::GetBool($name, $must)`	`bool`	GET 布尔
`Input::GetDateTime($name, $must)`	`string\|null`	RFC3339 格式时间
`Input::GetJson($name, $must)`	`array`	JSON 字符串 → 数组
`Input::Combi($name, $must, $xss)`	`string`	POST 优先，其次 GET
`Input::Raw()`	`string`	原始 `php://input`

Post/Get/Combi 的第三个参数 $xss = true 会对值调用 strip_tags 做基础 XSS 过滤。

示例：

$id      = Input::PostInt('id');                              // 0 也合法（严格判空）
$name    = Input::Post('name', true, true);                   // 必须且 XSS 过滤
$page    = Input::GetInt('page', false) ?: 1;                 // 非必须，默认 1
$enabled = Input::PostBool('enabled');                        // true / false 皆合法
$tags    = Input::PostJson('tags');                           // 解析为数组

替换默认失败响应类

Input 默认使用包内的 Ret::Fail。若需改用项目自定义响应类：

Input::setRetClass(\app\common\MyRet::class);

目标类需具备静态方法 Fail(int $code, mixed $data, string $msg): void。

Ret：JSON 响应（Ret::）

基础

Ret::Success(0, ['id' => 1, 'name' => 'x'], '操作成功');
Ret::Ok(['list' => [...]]);               // code=0 简写

Ret::Fail(400, [], '参数错误');
Ret::Error(400, '缺少字段 id');

输出格式统一：

{"code":0,"data":[],"echo":"成功"}

HTTP 快捷方法

方法	默认 code	默认 echo
`Ret::Ok($data, $echo)`	0	成功
`Ret::BadRequest($echo, $data)`	400	参数错误
`Ret::Unauthorized($echo, $data)`	401	鉴权失败
`Ret::Forbidden($echo, $data)`	403	权限不足
`Ret::NotFound($echo, $data)`	404	未找到数据
`Ret::ServerError($echo, $data)`	500	数据库错误
`Ret::Error($code, $echo, $data)`	任意	失败

内置 code → 默认提示词对照表

code	文案
0	成功
-1	登录失效请重新登录
400	参数错误
401	鉴权失败
403	权限不足
404	未找到数据
406 / 407	数据不符合期待
500	数据库错误
其他	失败

运行时配置

// 覆盖或追加状态码文案（i18n / 项目自定义）
Ret::setMessage(1001, '库存不足');
Ret::setMessages([-2 => '签名过期', 1002 => '频率超限']);
Ret::getMessages();

// 单元测试 / SSE 等特殊场景：只输出不 exit
Ret::setExitAfterSend(false);
Ret::setExitAfterSend(true, 0);    // 第二个参数是 exit code

// 自定义 Content-Type（传 null 则不发送任何头）
Ret::setContentType('application/json; charset=utf-8');
Ret::setContentType(null);

纯构造（不 exit / 不 echo）

$array = Ret::build(0, ['a' => 1]);
// ['code'=>0, 'data'=>['a'=>1], 'echo'=>'成功']

$json = Ret::toJson(400, [], '缺少参数 id');
// 直接返回 JSON 字符串，供队列/日志/测试使用

removeXSS() 助手函数

$cleanHtml = removeXSS($userInput);

未安装 ezyang/htmlpurifier 时原样返回。
非字符串入参原样返回。
白名单标签：div,b,strong,i,em,a[href|title],ul,ol,li,p[style],br,span[style],img[width|height|alt|src]。
白名单 CSS 属性：font,font-size,font-weight,font-style,font-family,text-decoration,padding-left,color,background-color,text-align。
HTML.TargetBlank = true。

CommitMessage\Analyzer：提交信息解析与描述生成

基于 Conventional Commits 规范。

use Tuuz\Input\CommitMessage\Analyzer;

$msg = "feat(input)!: add GetInt method

Adds a typed getter for query-string integers

BREAKING CHANGE: minimum PHP version bumped to 8.5
Refs: #123";

$a = Analyzer::from($msg);

基础 API

方法	说明
`$a->isValid()`	是否符合规范
`$a->getType()`	`feat` / `fix` / ...
`$a->getTypeDescription()`	类型英文描述
`$a->getScope()`	`input` 或 null
`$a->isBreakingChange()`	是否破坏性变更（header `!` 或 footer `BREAKING CHANGE`）
`$a->getSubject()`	主语
`$a->getBody()`	正文
`$a->getFooter()`	页脚
`$a->getErrors()`	校验错误数组
`$a->getMessage()`	原始消息
`$a->toArray()`	数组导出
`$a->generateDescription()`	生成带 Markdown 格式的人类可读描述
`$a->getBumpLevel()`	SemVer 升级级别：`major` / `minor` / `patch`，无法判断返回 null

generateDescription() 示例输出

**Type:** feat (A new feature)

**Scope:** input

⚠️ **BREAKING CHANGE**

**Subject:** add GetInt method

**Body:**
Adds a typed getter for query-string integers

**Footer:**
BREAKING CHANGE: minimum PHP version bumped to 8.5
Refs: #123

SemVer 升级级别判定

条件	级别
`!` 或 footer `BREAKING CHANGE`	`major`
`type === feat`	`minor`
`type === fix` 或 `type === perf`	`patch`
其他类型	`null`

支持的提交类型

Analyzer::getTypeDescriptions();

type	description
feat	A new feature
fix	A bug fix
docs	Documentation only changes
style	Changes that do not affect the meaning of the code
refactor	A code change that neither fixes a bug nor adds a feature
perf	A code change that improves performance
test	Adding missing tests or correcting existing tests
chore	Changes to the build process or auxiliary tools
build	Changes that affect the build system or external dependencies
ci	Changes to CI configuration files and scripts
revert	Reverts a previous commit

校验规则

Header 必须满足：type(scope)!: subject
subject 长度 ≤ 50，不允许以 . 结尾
body / footer 每行 ≤ 72 字符
错误信息通过 getErrors() 返回

命名空间类名对照

用途	推荐调用方式	完全限定名（FQSEN）
门面 Input	`Input::xxx()`	`Tuuz\Input\Facade\Input`
门面 Ret	`Ret::xxx()`	`Tuuz\Input\Facade\Ret`
核心 Input	`use Tuuz\Input\Input`	`Tuuz\Input\Input`
核心 Ret	`use Tuuz\Input\Ret`	`Tuuz\Input\Ret`
提交解析器	`use Tuuz\Input\CommitMessage\Analyzer`	`Tuuz\Input\CommitMessage\Analyzer`
XSS 助手	全局函数	`removeXSS()`（`Tuuz\Input\Helper\functions.php`）

License

MIT

tuuz / input

Maintainers

Package info

Statistics

Security