Skip to content

Commit 91d087d

Browse files
author
苏青安
committed
feat(docs): 添加中文 README 文件，包含安装和使用说明
1 parent c76a843 commit 91d087d

File tree

2 files changed

+299
-36
lines changed

2 files changed

+299
-36
lines changed

‎README.md‎

Lines changed: 139 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -1,57 +1,160 @@
1+
# hejunjie/schema-validator
12

3+
<div align="center">
4+
<a href="./README.md">English</a>｜<a href="./README.zh-CN.md">简体中文</a>
5+
<hr width="50%"/>
6+
</div>
27

8+
A simple and extensible PHP parameter validation library, supporting rule-based definitions and custom extensions, suitable for any structured data verification scenarios
39

10+
---
11+
12+
## 📦 Installation method
13+
14+
Install using Composer：
415

5-
### 🟦 类型类
16+
```bash
17+
composer require hejunjie/schema-validator
18+
```
619

7-
- ​`StringRule`：内容必须为字符串
8-
- ​`IntegerRule`：内容必须为整数
9-
- ​`BooleanRule`：内容必须为布尔值 true/false
10-
- ​`ArrayRule`：内容必须为数组
11-
- ​`ObjectRule`：内容必须为对象
12-
- ​`FloatRule`：内容必须为浮点数
13-
- ​`NumericRule`：内容必须为数字（包含整数、小数、科学计数法等）
20+
---
21+
22+
## 🚀 Usage
23+
24+
Support multiple rule definitions + throw exceptions + custom extensions：
25+
26+
```php
27+
use Hejunjie\SchemaValidator\Validator;
28+
use Hejunjie\SchemaValidator\Exceptions\ValidationException;
29+
30+
$data = [
31+
'name' => '张三',
32+
'age' => 28,
33+
'email' => 'invalid-email',
34+
];
35+
36+
// Custom extension. If true is returned, the rule passes; otherwise, it is considered as failing
37+
Validator::extend('is_zh', function ($field, $value, $params = null) {
38+
if (preg_match('/^[\x{4e00}-\x{9fa5}]+$/u', $value)) {
39+
return true;
40+
}
41+
});
42+
43+
try {
44+
Validator::validate($data, [
45+
'name' => ['is_zh', 'string', 'minLength:2'],
46+
'age' => ['integer', 'between:18,60'],
47+
'email' => ['required', 'email'],
48+
]);
49+
echo "Verified by ✅";
50+
} catch (ValidationException $e) {
51+
echo "Validation failed ❌" . PHP_EOL;
52+
print_r($e->getErrors());
53+
}
54+
55+
// Return the fields and rules indicating whether it is passed or failed:
56+
// Validation failed ❌
57+
// Array
58+
// (
59+
// [email] => Array
60+
// (
61+
// [0] => email
62+
// )
63+
64+
// )
65+
```
1466

1567
---
1668

17-
### 🟩 比较类
69+
## ✅ Default support rule
70+
71+
The following rules are already supported in a built-in manner and are implemented as independent classes, allowing for free extension or replacement：
1872

19-
- ​`MinRule`：数值大小或字符串长度不允许小于指定值
20-
- ​`MaxRule`：数字大小或字符串长度不允许超过指定值
21-
- ​`BetweenRule`：数字大小或字符串长度必须在指定的最小值和最大值之间
22-
- ​`LengthRule`：字符串长度必须等于指定值
23-
- ​`MinLengthRule`：字符串的长度不允许小于指定值
24-
- ​`MaxLengthRule`：字符串的长度不允许超过指定值
25-
- ​`GtRule`：数字必须大于指定值
26-
- ​`LtRule`：数字必须小于指定值
27-
- ​`GteRule`：数字必须大于或等于指定值
28-
- ​`LteRule`：数字必须小于或等于指定值
73+
### Type class
74+
75+
| Rule Name | Function Description | Parameter Format | Example Usage |
76+
| ------------- | ------------------------------------------------------------------------------ | ---------------- | -------------------------- |
77+
| `StringRule` | Verify whether it is a string | `string` | `['param' => ['string']]` |
78+
| `IntegerRule` | Verify whether it is an integer | `integer` | `['param' => ['integer']]` |
79+
| `BooleanRule` | Verify whether it is a boolean value (true/false or 0/1) | `boolean` | `['param' => ['boolean']]` |
80+
| `ArrayRule` | Verify whether it is an array | `array` | `['param' => ['array']]` |
81+
| `ObjectRule` | Verify whether it is an object | `object` | `['param' => ['object']]` |
82+
| `FloatRule` | Verify whether it is a floating-point number | `float` | `['param' => ['float']]` |
83+
| `NumericRule` | Verify whether it is a number (including integer, floating-point string, etc.) | `numeric` | `['param' => ['numeric']]` |
84+
85+
---
86+
87+
### Compare class
88+
89+
| Rule Name | Function Description | Parameter Format | Example Usage |
90+
| --------------- | -------------------------------------------------------------------------------------------------------- | ---------------- | -------------------------------- |
91+
| `MinRule` | The numerical value or string length cannot be less than the specified value | `min` | `['param' => ['min:2']]` |
92+
| `MaxRule` | The size of numbers or the length of strings are not allowed to exceed the specified value | `max` | `['param' => ['max:2']]` |
93+
| `BetweenRule` | The size of a number or the length of a string must fall within the specified minimum and maximum values | `between` | `['param' => ['between:18,60']]` |
94+
| `LengthRule` | The length of the string must be equal to the specified value | `length` | `['param' => ['length:10']]` |
95+
| `MinLengthRule` | The length of the string is not allowed to exceed the specified value | `min_length` | `['param' => ['min_length:2']]` |
96+
| `MaxLengthRule` | The length of the string cannot be less than the specified value | `max_length` | `['param' => ['max_length:20']]` |
97+
| `GtRule` | The number must be greater than the specified value | `gt` | `['param' => ['gt:2']]` |
98+
| `LtRule` | The number must be less than the specified value | `lt` | `['param' => ['lt:2']]` |
99+
| `GteRule` | The number must be greater than or equal to the specified value | `gte` | `['param' => ['gte:2']]` |
100+
| `LteRule` | The number must be less than or equal to the specified value | `lte` | `['param' => ['lte:2']]` |
29101

30102
---
31103

32-
### 🟨 格式类
104+
### Format class
33105

34-
- ​`EmailRule`：内容必须是邮箱格式
35-
- ​`MobileRule`：内容必须是中国大陆手机号格式
36-
- ​`UrlRule`：内容必须是URL
37-
- ​`IpRule`：内容必须是有效的 IP 地址（IPv4 或 IPv6）
38-
- ​`JsonRule`：内容必须是有效的Json字符串
39-
- ​`AlphaRule`：内容只能包含字母
40-
- ​`AlphaNumRule`：内容只能包含字母和数字
41-
- ​`AlphaDashRule`：内容只能包含字母、数字、破折号、下划线
106+
| Rule Name | Function Description | Parameter Format | Example Usage |
107+
| --------------- | ------------------------------------------------------------------------- | ---------------- | ----------------------------- |
108+
| `EmailRule` | The content must be in email format | `email` | `['param' => ['email']]` |
109+
| `MobileRule` | The content must be in the format of a mainland China mobile phone number | `mobile` | `['param' => ['mobile']]` |
110+
| `UrlRule` | The content must be a URL | `url` | `['param' => ['url']]` |
111+
| `IpRule` | The content must be a valid IP address (IPv4 or IPv6) | `ip` | `['param' => ['ip']]` |
112+
| `JsonRule` | The content must be a valid JSON string | `json` | `['param' => ['json']]` |
113+
| `AlphaRule` | The content can only contain letters | `alpha` | `['param' => ['alpha']]` |
114+
| `AlphaNumRule` | The content can only contain letters and numbers | `alpha_num` | `['param' => ['alpha_num']]` |
115+
| `AlphaDashRule` | The content can only contain letters, numbers, dashes, and underscores | `alpha_dash` | `['param' => ['alpha_dash']]` |
42116

43117
---
44118

45-
### 🟥 布尔类
119+
### Boolean class
46120

47-
- ​`RequiredRule`：内容必须存在且不为空
48-
- ​`AcceptedRule`：内容只能为 yes、on、1、true
49-
- ​`DeclinedRule`：内容只能为 no、off、0、false
121+
| Rule Name | Function Description | Parameter Format | Example Usage |
122+
| -------------- | ---------------------------------------------------- | ---------------- | --------------------------- |
123+
| `RequiredRule` | The content must exist and not be empty | `required` | `['param' => ['required']]` |
124+
| `AcceptedRule` | The content can only be "yes", "on", "1", or "true" | `accepted` | `['param' => ['accepted']]` |
125+
| `DeclinedRule` | The content can only be "no", "off", "0", or "false" | `declined` | `['param' => ['declined']]` |
50126

51127
---
52128

53-
### 🟪 自定义类
129+
### Custom class
130+
131+
| Rule Name | Function Description | Parameter Format | Example Usage |
132+
| ---------------- | ------------------------------------------------ | ---------------- | ------------------------------ |
133+
| `StartsWithRule` | The content must start with the specified string | `starts_with` | `['param' => ['starts_with']]` |
134+
| `EndsWithRule` | The content must end with the specified string | `ends_with` | `['param' => ['ends_with']]` |
135+
| `ContainsRule` | The content must contain the specified string | `contains` | `['param' => ['contains']]` |
136+
137+
> The error message is returned as an array of rule names, and the prompt text can be customized
138+
139+
---
140+
141+
## 🧩 Purpose & Original Intent
142+
143+
In daily development, we often need to perform structured validation on incoming data, but many existing libraries are either bulky, rely on frameworks, or are not flexible in terms of extension (such as Laravel Validator).
144+
145+
The goal of this library is to:
146+
147+
- ✅ Zero dependencies, suitable for any PHP project
148+
- ✅ Validation for structured arrays
149+
- ✅ Each rule is encapsulated independently, facilitating customization and expansion
150+
- ✅ More suitable for field prompts and error handling in the Chinese context
151+
152+
If you need a simple, clear, and rule-controlled data verification tool, it may be just right for you.
153+
154+
---
155+
156+
## 🙌 Welcome to contribute
157+
158+
Welcome to raise issues, submit pull requests, or directly fork for use!
54159

55-
- ​`StartsWithRule`：内容必须以指定字符串开头
56-
- ​`EndsWithRule`：内容必须以指定字符串结尾
57-
- ​`ContainsRule`：内容必须包含指定字符串
160+
If you have other commonly used validation rules, feel free to add them, even if it's just a line of regular expression.

‎README.zh-CN.md‎

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
# hejunjie/schema-validator
2+
3+
<div align="center">
4+
<a href="./README.md">English</a>｜<a href="./README.zh-CN.md">简体中文</a>
5+
<hr width="50%"/>
6+
</div>
7+
8+
一个简单且可扩展的 PHP 参数验证库，支持规则式定义与自定义扩展，适用于任何结构化数据校验场景
9+
10+
---
11+
12+
## 📦 安装方式
13+
14+
使用 Composer 安装：
15+
16+
```bash
17+
composer require hejunjie/schema-validator
18+
```
19+
20+
---
21+
22+
## 🚀 使用方式
23+
24+
支持多规则定义 + 抛出异常 + 自定义扩展：
25+
26+
```php
27+
use Hejunjie\SchemaValidator\Validator;
28+
use Hejunjie\SchemaValidator\Exceptions\ValidationException;
29+
30+
$data = [
31+
'name' => '张三',
32+
'age' => 28,
33+
'email' => 'invalid-email',
34+
];
35+
36+
// 自定义扩展，返回 true 则规则通过，否则均视为不通过
37+
Validator::extend('is_zh', function ($field, $value, $params = null) {
38+
if (preg_match('/^[\x{4e00}-\x{9fa5}]+$/u', $value)) {
39+
return true;
40+
}
41+
});
42+
43+
try {
44+
Validator::validate($data, [
45+
'name' => ['is_zh', 'string', 'minLength:2'],
46+
'age' => ['integer', 'between:18,60'],
47+
'email' => ['required', 'email'],
48+
]);
49+
echo "验证通过 ✅";
50+
} catch (ValidationException $e) {
51+
echo "验证失败 ❌" . PHP_EOL;
52+
print_r($e->getErrors());
53+
}
54+
55+
// 返回是否通过以及不通过的字段与规则：
56+
// 验证失败 ❌
57+
// Array
58+
// (
59+
// [email] => Array
60+
// (
61+
// [0] => email
62+
// )
63+
64+
// )
65+
```
66+
67+
---
68+
69+
## ✅ 默认支持规则
70+
71+
以下规则已内置支持，均以独立类形式实现，可自由扩展或替换：
72+
73+
### 类型类
74+
75+
| 规则名 | 功能描述 | 参数格式 | 示例用法 |
76+
| ------------- | ------------------------------------------ | --------- | -------------------------- |
77+
| `StringRule` | 验证是否为字符串 | `string` | `['param' => ['string']]` |
78+
| `IntegerRule` | 验证是否为整数 | `integer` | `['param' => ['integer']]` |
79+
| `BooleanRule` | 验证是否为布尔值（true/false 或 0/1） | `boolean` | `['param' => ['boolean']]` |
80+
| `ArrayRule` | 验证是否为数组 | `array` | `['param' => ['array']]` |
81+
| `ObjectRule` | 验证是否为对象 | `object` | `['param' => ['object']]` |
82+
| `FloatRule` | 验证是否为浮点数 | `float` | `['param' => ['float']]` |
83+
| `NumericRule` | 验证是否为数字（包括整型、浮点型字符串等） | `numeric` | `['param' => ['numeric']]` |
84+
85+
---
86+
87+
### 比较类
88+
89+
| 规则名 | 功能描述 | 参数格式 | 示例用法 |
90+
| --------------- | -------------------------------------------------- | ------------ | -------------------------------- |
91+
| `MinRule` | 数值大小或字符串长度不允许小于指定值 | `min` | `['param' => ['min:2']]` |
92+
| `MaxRule` | 数字大小或字符串长度不允许超过指定值 | `max` | `['param' => ['max:2']]` |
93+
| `BetweenRule` | 数字大小或字符串长度必须在指定的最小值和最大值之间 | `between` | `['param' => ['between:18,60']]` |
94+
| `LengthRule` | 字符串长度必须等于指定值 | `length` | `['param' => ['length:10']]` |
95+
| `MinLengthRule` | 字符串的长度不允许超过指定值 | `min_length` | `['param' => ['min_length:2']]` |
96+
| `MaxLengthRule` | 字符串的长度不允许小于指定值 | `max_length` | `['param' => ['max_length:20']]` |
97+
| `GtRule` | 数字必须大于指定值 | `gt` | `['param' => ['gt:2']]` |
98+
| `LtRule` | 数字必须小于指定值 | `lt` | `['param' => ['lt:2']]` |
99+
| `GteRule` | 数字必须大于或等于指定值 | `gte` | `['param' => ['gte:2']]` |
100+
| `LteRule` | 数字必须小于或等于指定值 | `lte` | `['param' => ['lte:2']]` |
101+
102+
---
103+
104+
### 格式类
105+
106+
| 规则名 | 功能描述 | 参数格式 | 示例用法 |
107+
| --------------- | ---------------------------------------- | ------------ | ----------------------------- |
108+
| `EmailRule` | 内容必须是邮箱格式 | `email` | `['param' => ['email']]` |
109+
| `MobileRule` | 内容必须是中国大陆手机号格式 | `mobile` | `['param' => ['mobile']]` |
110+
| `UrlRule` | 内容必须是 URL | `url` | `['param' => ['url']]` |
111+
| `IpRule` | 内容必须是有效的 IP 地址（IPv4 或 IPv6） | `ip` | `['param' => ['ip']]` |
112+
| `JsonRule` | 内容必须是有效的 Json 字符串 | `json` | `['param' => ['json']]` |
113+
| `AlphaRule` | 内容只能包含字母 | `alpha` | `['param' => ['alpha']]` |
114+
| `AlphaNumRule` | 内容只能包含字母和数字 | `alpha_num` | `['param' => ['alpha_num']]` |
115+
| `AlphaDashRule` | 内容只能包含字母、数字、破折号、下划线 | `alpha_dash` | `['param' => ['alpha_dash']]` |
116+
117+
---
118+
119+
### 布尔类
120+
121+
| 规则名 | 功能描述 | 参数格式 | 示例用法 |
122+
| -------------- | ---------------------------- | ---------- | --------------------------- |
123+
| `RequiredRule` | 内容必须存在且不为空 | `required` | `['param' => ['required']]` |
124+
| `AcceptedRule` | 内容只能为 yes、on、1、true | `accepted` | `['param' => ['accepted']]` |
125+
| `DeclinedRule` | 内容只能为 no、off、0、false | `declined` | `['param' => ['declined']]` |
126+
127+
---
128+
129+
### 自定义类
130+
131+
| 规则名 | 功能描述 | 参数格式 | 示例用法 |
132+
| ---------------- | ------------------------ | ------------- | ------------------------------ |
133+
| `StartsWithRule` | 内容必须以指定字符串开头 | `starts_with` | `['param' => ['starts_with']]` |
134+
| `EndsWithRule` | 内容必须以指定字符串结尾 | `ends_with` | `['param' => ['ends_with']]` |
135+
| `ContainsRule` | 内容必须包含指定字符串 | `contains` | `['param' => ['contains']]` |
136+
137+
> 错误信息返回为规则名数组，可自行定义提示文案。
138+
139+
---
140+
141+
## 🧩 用途 & 初衷
142+
143+
在日常开发中，我们常常需要对传入的数据进行结构化验证，但很多现有的库要么体积庞大、依赖框架，要么扩展不灵活（比如 Laravel Validator ）。
144+
145+
这个库的目标是：
146+
147+
- ✅ 零依赖，适用于任何 PHP 项目
148+
- ✅ 面向结构化数组进行验证
149+
- ✅ 每条规则独立封装，方便自定义与扩展
150+
- ✅ 更适合中文语境下的字段提示与错误处理
151+
152+
如果你需要一个简单清晰、规则可控的数据验证工具，它可能正好适合你。
153+
154+
---
155+
156+
## 🙌 欢迎贡献
157+
158+
欢迎提出 Issue、提交 PR 或直接 Fork 使用！
159+
160+
如果你有其他常用验证规则，也欢迎补充，哪怕是一行正则。

0 commit comments

Comments
 (0)