Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Commit 7aaf9f9

Browse files
add en doc
1 parent ac20d27 commit 7aaf9f9

24 files changed

+2100
-0
lines changed

‎docs/en/.gitbook.yaml

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
root: ./
2+
structure:
3+
readme: README.md
4+
summary: SUMMARY.md

‎docs/en/README.md

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# php-serialize
2+
3+
**php-serialize** 是一个功能强大的基于属性(attribute)的 PHP 序列化库(需要 **PHP ≥ 8.1**)。
4+
它允许你将对象映射为数组或 JSON,并且可以基于相同的属性 **自动生成 OpenAPI 文档**。
5+
6+
> 🚀 统一解决方案,支持 API 数据序列化和文档生成。
7+
8+
## ✨ 功能特色
9+
10+
- 🏷️ 属性别名映射
11+
- 🔄 自动类型转换(例如 `DateTime ↔ string`)
12+
- 🔁 支持深度对象嵌套
13+
- ❌ 支持跳过/排除字段
14+
- 🧩 递归 DTO(数据传输对象)序列化
15+
- 🧬 **基于对象定义自动生成 OpenAPI schema**
16+
- ⚙️ 与框架无关 — 兼容 Laravel、Symfony 等框架

‎docs/en/SUMMARY.md

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# Summary
2+
3+
* [介绍](README.md)
4+
* [快速开始](getting-started.md)
5+
6+
## 属性转换
7+
8+
* [基本类型转换](mapper/base-mapper.md)
9+
* [Null值转换](mapper/null-mapper.md)
10+
* [枚举转换](mapper/enum-mapper.md)
11+
* [数组对象转换](mapper/array-mapper.md)
12+
* [联合类型转换](mapper/union-mapper.md)
13+
14+
## 注解类使用
15+
16+
* [属性分组](annotation/group-annotation.md)
17+
* [输入/输出映射](annotation/alisa-annotation.md)
18+
* [Mapper映射](annotation/mapper-annotation.md)
19+
* [输入/输出忽略](annotation/ignore-annotation.md)
20+
* [时间格式映射](annotation/date-annotation.md)
21+
* [自定义注解](annotation/customer-annotation.md)
22+
23+
## 参数快速模拟生成
24+
25+
* [简单属性Faker](faker/value-faker.md)
26+
* [集合Faker](faker/collection-faker.md)
27+
* [嵌套Faker](faker/nested-faker.md)
28+
* [方法Faker](faker/method-faker.md)
29+
30+
## 自动创建OpenApi文档
31+
32+
* [基础演示](openapi/base-openapi.md)
33+
* [参数注解](openapi/annotation.md)
34+
* [重写注解](openapi/override-annotation.md)
35+
* [配置](openapi/config.md)
36+
* [启动服务](openapi/launch.md)

‎docs/en/annotation/alisa-annotation.md

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
## 名称映射
2+
3+
### 基础使用
4+
5+
```php
6+
use Astral\Serialize\Attributes\InputName;
7+
use Astral\Serialize\Attributes\OutputName;
8+
use Astral\Serialize\Serialize;
9+
10+
class User extends Serialize {
11+
// 输入时使用不同的属性名
12+
#[InputName('user_name')]
13+
public string $name;
14+
15+
// 输出时使用不同的属性名
16+
#[OutputName('user_id')]
17+
public int $id;
18+
19+
// 同时支持输入和输出不同名称
20+
#[InputName('register_time')]
21+
#[OutputName('registeredAt')]
22+
public DateTime $createdAt;
23+
}
24+
25+
// 使用不同名称的输入数据
26+
$user = User::from([
27+
'user_name' => '张三', // 映射到 $name
28+
'id' => 123, // 保持不变
29+
'register_time' => '2023年01月01日 10:00:00' // 映射到 $createdAt
30+
]);
31+
32+
// 输出数据
33+
$userArray = $user->toArray();
34+
// $userArray 的内容:
35+
// [
36+
// 'name' => '张三',
37+
// 'user_id' => 123,
38+
// 'registeredAt' => '2023年01月01日 10:00:00'
39+
// ]
40+
```
41+
42+
### 多输入/输出名称处理
43+
44+
```php
45+
use Astral\Serialize\Attributes\InputName;
46+
use Astral\Serialize\Attributes\OutputName;
47+
use Astral\Serialize\Serialize;
48+
49+
class MultiOutputUser extends Serialize {
50+
// 多个输出名称
51+
#[OutputName('user_id')]
52+
#[OutputName('id')]
53+
#[OutputName('userId')]
54+
public int $id;
55+
56+
// 多个输出名称 按照声明顺序取地一个匹配的name
57+
#[InputName('user_name')]
58+
#[InputName('other_name')]
59+
#[InputName('userName')]
60+
public int $name;
61+
62+
}
63+
64+
// 场景1:使用第一个匹配的输入名称
65+
$user1 = MultiInputUser::from([
66+
'user_name' => '张三' // 使用 'user_name'
67+
]);
68+
echo $user1->name; // 输出 '张三'
69+
70+
// 场景2:使用第二个匹配的输入名称
71+
$user2 = MultiInputUser::from([
72+
'other_name' => '李四' // 使用 'other_name'
73+
]);
74+
echo $user2->name; // 输出 '李四'
75+
76+
// 场景3:使用最后的输入名称
77+
$user3 = MultiInputUser::from([
78+
'userName' => '王五' // 使用 'userName'
79+
]);
80+
echo $user3->name; // 输出 '王五'
81+
82+
// 场景4:传入多个的时候 按照声明顺序取地一个匹配的name
83+
$user4 = MultiInputUser::from([
84+
'userName' => '王五',
85+
'other_name' => '李四',
86+
'user_name' => '张三',
87+
]);
88+
echo $user4->name; // 输出 '张三'
89+
90+
// 创建用户对象
91+
$user = MultiOutputUser::from([
92+
'id' => 123,
93+
'name' => '张三'
94+
]);
95+
96+
// 转换为数组
97+
// tips: 因为id 有多个outputname 所以输出了 ['user_id','id','userId']
98+
$userArray = $user->toArray();
99+
// $userArray 的内容:
100+
// [
101+
// 'user_id' => 123,
102+
// 'id' => 123,
103+
// 'userId' => 123,
104+
// ]
105+
```
106+
107+
### 复杂映射场景
108+
109+
```php
110+
use Astral\Serialize\Serialize;
111+
112+
class ComplexUser extends Serialize {
113+
// 嵌套对象的名称映射
114+
#[InputName('user_profile')]
115+
public UserProfile $profile;
116+
117+
// 数组元素的名称映射
118+
#[InputName('user_tags')]
119+
public array $tags;
120+
}
121+
122+
// 处理复杂的输入结构
123+
$complexUser = ComplexUser::from([
124+
'user_profile' => [
125+
'nickname' => '小明',
126+
'age' => 25
127+
],
128+
'user_tags' => ['developer', 'programmer']
129+
]);
130+
131+
// 转换为标准数组
132+
$complexUserArray = $complexUser->toArray();
133+
// $complexUserArray 的内容:
134+
// [
135+
// 'profile' => UserProfile Object ([
136+
// 'nickname' => '小明',
137+
// 'age' => 25
138+
// ]),
139+
// 'tags' => ['developer', 'programmer']
140+
// ]
141+
```
Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
### 自定义注解类实现
2+
3+
你可以通过自定义注解类,灵活地扩展序列化库的输入输出处理逻辑。
4+
5+
---
6+
7+
#### 入参处理注解类
8+
9+
实现 `InputValueCastInterface` 接口,重写其中的 `match` 和 `resolve` 方法,来自定义输入数据的转换和处理。
10+
11+
- **`match`**:用于判断是否对当前值进行处理,返回 `true` 表示进入 `resolve`。
12+
- **`resolve`**:对匹配的输入值进行转换,并返回转换后的结果。
13+
14+
示例:给输入值添加自定义前缀的注解类
15+
16+
```php
17+
use Astral\Serialize\Contracts\Attribute\InputValueCastInterface;
18+
use Attribute;
19+
20+
#[Attribute(Attribute::TARGET_PROPERTY | Attribute::TARGET_CLASS)]
21+
class CustomerInput implements InputValueCastInterface
22+
{
23+
public function __construct(
24+
public string $prefix = '',
25+
) {
26+
}
27+
28+
public function match(mixed $value, DataCollection $collection, InputValueContext $context): bool
29+
{
30+
// 对所有输入值都生效
31+
return true;
32+
}
33+
34+
public function resolve(mixed $value, DataCollection $collection, InputValueContext $context): mixed
35+
{
36+
// 给输入值添加前缀
37+
return $this->prefix . $value;
38+
}
39+
}
40+
````
41+
42+
### 输出处理注解类
43+
44+
输出处理注解与输入处理注解类似,只是实现的接口不同——需要实现 `OutputValueCastInterface`,用以对序列化输出的值进行自定义转换。
45+
46+
示例:给序列化输出的值添加自定义后缀的注解类
47+
48+
```php
49+
use Astral\Serialize\Contracts\Attribute\OutputValueCastInterface;
50+
use Attribute;
51+
52+
#[Attribute(Attribute::TARGET_PROPERTY | Attribute::TARGET_CLASS)]
53+
class CustomerOutput implements OutputValueCastInterface
54+
{
55+
public function __construct(
56+
public string $suffix = '',
57+
) {
58+
}
59+
60+
public function match(mixed $value, DataCollection $collection, OutputValueContext $context): bool
61+
{
62+
// 对所有输出值都生效
63+
return true;
64+
}
65+
66+
public function resolve(mixed $value, DataCollection $collection, OutputValueContext $context): mixed
67+
{
68+
// 给输出值添加后缀
69+
return $value . $this->suffix;
70+
}
71+
}
72+
```
73+

‎docs/en/annotation/date-annotation.md

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
## 时间转换
2+
3+
1. 格式灵活性
4+
支持多种输入和输出时间格式
5+
可以轻松处理不同地区的日期表示
6+
2. 时区处理
7+
支持在不同时区间转换
8+
自动处理时间的时区偏移
9+
3. 类型安全
10+
自动将字符串转换为 DateTime 对象
11+
保证类型的一致性和正确性
12+
13+
### 基础使用
14+
15+
```php
16+
use Astral\Serialize\Attributes\Input\InputDateFormat;
17+
use Astral\Serialize\Attributes\Output\OutputDateFormat;
18+
use Astral\Serialize\Serialize;
19+
20+
class TimeExample extends Serialize {
21+
22+
// 输入时间格式转换
23+
#[InputDateFormat('Y-m-d')]
24+
public DateTime $dateTime;
25+
26+
// 输入时间格式转换
27+
#[InputDateFormat('Y-m-d')]
28+
public string $dateDateString;
29+
30+
// 输出时间格式转换
31+
#[OutputDateFormat('Y/m/d H:i')]
32+
public DateTime|string $processedAt;
33+
34+
35+
// 支持多种时间格式
36+
#[InputDateFormat('Y-m-d H:i:s')]
37+
#[OutputDateFormat('Y-m-d')]
38+
public string $createdAt;
39+
}
40+
41+
// 创建订单对象
42+
$order = TimeExample::from([
43+
'dateTime' => new DateTime('2023年08月11日'), // 输入格式:Y-m-d
44+
'dateDateString' => '2023年08月15日', // 输入格式:Y-m-d
45+
'processedAt' => '2023年08月16日 14:30', // 输入默认格式 也支持DateTime对象
46+
'createdAt' => '2023年08月16日 14:45:30' // 输入格式:Y-m-d H:i:s
47+
]);
48+
49+
// 转换为数组
50+
$orderArray = $order->toArray();
51+
// $orderArray 的内容:
52+
// [
53+
// 'dateTime' => '2023年08月11日',
54+
// ’dateDateString' => '2023年08月15日',
55+
// 'processedAt' => '2023年08月16日 14:30',
56+
// 'createdAt' => '2023年08月16日'
57+
// ]
58+
```
59+
60+
### 带时区的时间转换
61+
62+
```php
63+
64+
use Astral\Serialize\Attributes\Input\InputDateFormat;
65+
use Astral\Serialize\Attributes\Output\OutputDateFormat;
66+
use Astral\Serialize\Serialize;
67+
68+
class AdvancedTimeUser extends Serialize {
69+
// 支持时区转换
70+
#[InputDateFormat('Y-m-d H:i:s', timezone: 'UTC')]
71+
#[OutputDateFormat('Y-m-d H:i:s', timezone: 'Asia/Shanghai')]
72+
public DateTime $registeredAt;
73+
74+
// 支持不同地区的时间格式
75+
#[InputDateFormat('d/m/Y')] // 英国格式
76+
#[OutputDateFormat('Y-m-d')] // 标准格式
77+
public DateTime $birthDate;
78+
}
79+
80+
// 使用高级时间转换
81+
$advancedUser = AdvancedTimeUser::from([
82+
'registeredAt' => '2023年08月16日 10:00:00', // UTC 时间
83+
'birthDate' => '15/08/1990' // 英国日期格式
84+
]);
85+
86+
$advancedUserArray = $advancedUser->toArray();
87+
// $advancedUserArray 的内容:
88+
// [
89+
// 'registeredAt' => '2023年08月16日 18:00:00', // 转换为上海时区
90+
// 'birthDate' => '1990年08月15日'
91+
// ]
92+
```

0 commit comments

Comments
(0)

AltStyle によって変換されたページ (->オリジナル) /