Skip to content

Commit 3220fe4

Browse files
astral-dataastral-data
committed
gitbook zh success
1 parent cab9685 commit 3220fe4

File tree

1 file changed

+113
-142
lines changed

1 file changed

+113
-142
lines changed

‎docs/zh/annotation/group-annotation.md

Lines changed: 113 additions & 142 deletions
Original file line numberDiff line numberDiff line change
@@ -1,191 +1,162 @@
1-
## 属性分组
1+
## 属性分组（Groups）
22

33
属性分组提供了一种灵活的方式来控制属性的输入和输出行为，允许在不同场景下精细地管理数据转换。
44

5-
### 基本用法
5+
---
66

7-
在属性上使用 `#[Groups]` 注解来指定属性所属的分组。
7+
### 🧠 分组原理说明
8+
9+
- 使用 `#[Groups(...)]` 注解可将属性归类到一个或多个分组中。
10+
- 支持：
11+
- **输入时** 按分组过滤数据字段
12+
- **输出时** 按分组筛选输出字段
13+
- 未指定分组的属性将自动归入 `"default"` 分组。
14+
15+
---
16+
17+
### ✨ 基本示例
818

919
```php
1020
use Astral\Serialize\Attributes\Groups;
1121
use Astral\Serialize\Serialize;
1222

1323
class User extends Serialize {
1424

15-
#[Groups('update','detail')]
25+
#[Groups('update', 'detail')]
1626
public string $id;
1727

1828
#[Groups('create', 'update', 'detail')]
1929
public string $name;
2030

21-
#[Groups('create','detail')]
31+
#[Groups('create', 'detail')]
2232
public string $username;
2333

2434
#[Groups('other')]
2535
public string $sensitiveData;
2636

27-
// 没有指定Group 的属性将会被默认分组在default分组中
37+
// 未指定分组，默认为 default 分组
2838
public string $noGroupInfo;
2939

30-
// 构造函数参数也支持分组
3140
public function __construct(
32-
#[Groups('create','detail')]
41+
#[Groups('create', 'detail')]
3342
public readonly string $email,
34-
35-
#[Groups('update','detail')]
43+
44+
#[Groups('update', 'detail')]
3645
public readonly int $score
3746
) {}
3847
}
48+
```
3949

50+
### 按分组接收
4051

52+
```php
53+
// 使用 create 分组创建用户，只接受 group=create 的字段
54+
$user = User::setGroups(['create'])->from([
55+
'id' => 1,
56+
'name' => '李四',
57+
'score' => 100,
58+
'username' => 'username',
59+
'email' => 'zhangsan@example.com',
60+
'sensitiveData' => '机密信息',
61+
'noGroupInfo' => '默认信息'
62+
]);
63+
64+
$user->toArray();
65+
/*
66+
[
67+
'name' => '李四',
68+
'username' => 'username',
69+
'email' => 'zhangsan@example.com',
70+
]
71+
*/
72+
```
73+
74+
### 按分组输出
4175

42-
// 使用 默认分组展示所有信息
43-
$user1 = User::from(
44-
id:1,
45-
name: '李四',
46-
score: 100,
47-
username: 'username',
48-
email: 'zhangsan@example.com',
49-
sensitiveData:'机密信息',
50-
noGroupInfo:'默认分组信息'
51-
);
52-
53-
// 使用默认分组 toArray，展示所有信息
54-
$defaultArray = $user1->toArray();
55-
// $defaultArray 的内容:
56-
// [
57-
// 'id' => '1',
58-
// 'name' => '李四',
59-
// 'username' => 'username',
60-
// 'score' => 100,
61-
// 'email' => 'zhangsan@example.com',
62-
// 'sensitiveData' => '机密信息',
63-
// 'noGroupInfo' => '默认分组信息'
64-
// ]
65-
66-
// 指定分组内容输入
67-
$defaultArray = $user1->withGroups('create')->toArray();
68-
// 输出内容
69-
// [
70-
// 'name' => '李四',
71-
// 'username' => 'username',
72-
// 'email' => 'zhangsan@example.com',
73-
// ]
74-
75-
$defaultArray = $user1->withGroups(['detail','other'])->toArray();
76-
// 输出内容
77-
// [
78-
// 'id' => '1',
79-
// 'name' => '李四',
80-
// 'username' => 'username',
81-
// 'score' => 100,
82-
// 'email' => 'zhangsan@example.com',
83-
// 'sensitiveData' => '机密信息',
84-
// ]
85-
86-
87-
// 使用 create 分组创建用户 只会接受group为create的数据信息
88-
$user2 = User::setGroups(['create'])->from(
89-
id:1,
90-
name: '李四',
91-
score: 100,
92-
username: 'username',
93-
email: 'zhangsan@example.com',
94-
sensitiveData:'机密信息',
95-
noGroupInfo:'默认分组信息'
96-
);
97-
98-
// 使用 create 分组 toArray
99-
$createArray = $user2->toArray();
100-
// $createArray 的内容:
101-
// [
102-
// 'name' => '李四',
103-
// 'username' => 'username',
104-
// 'email' => 'zhangsan@example.com',
105-
// ]
106-
107-
// 使用 update 分组更新用户 只会接受group为update的数据信息
108-
$user3 = User::setGroups(['update'])->from(
109-
id:1,
110-
name: '李四',
111-
score: 100,
112-
username: 'username',
113-
email: 'zhangsan@example.com',
114-
sensitiveData:'机密信息',
115-
noGroupInfo:'默认分组信息'
116-
);
117-
118-
// 使用 update 分组 toArray
119-
$updateArray = $user3->toArray();
120-
// $updateArray 的内容:
121-
// [
122-
// 'id' => '1',
123-
// 'name' => '李四',
124-
// 'score' => 100,
125-
// ]
126-
127-
// 使用 detail 和 other 展示用户 会接受group为detail和other的数据信息
128-
$user4 = User::setGroups(['detail','other'])->from(
129-
id:1,
130-
name: '李四',
131-
score: 100,
132-
username: 'username',
133-
email: 'zhangsan@example.com',
134-
sensitiveData:'机密信息',
135-
noGroupInfo:'默认分组信息'
136-
);
137-
138-
// 使用多个分组 toArray
139-
$multiGroupArray = $user4->toArray();
140-
// $multiGroupArray 的内容:
141-
// [
142-
// 'id' => '1',
143-
// 'name' => '李四',
144-
// 'username' => 'username',
145-
// 'score' => 100,
146-
// 'email' => 'zhangsan@example.com',
147-
// 'sensitiveData' => '机密信息',
148-
// ]
76+
```php
77+
$user = User::from([
78+
'id' => 1,
79+
'name' => '李四',
80+
'score' => 100,
81+
'username' => 'username',
82+
'email' => 'zhangsan@example.com',
83+
'sensitiveData' => '机密信息',
84+
'noGroupInfo' => '默认信息'
85+
]);
86+
87+
// 默认输出所有字段
88+
$user->toArray();
89+
/*
90+
[
91+
'id' => '1',
92+
'name' => '李四',
93+
'username' => 'username',
94+
'score' => 100,
95+
'email' => 'zhangsan@example.com',
96+
'sensitiveData' => '机密信息',
97+
'noGroupInfo' => '默认信息'
98+
]
99+
*/
100+
101+
// 指定输出分组
102+
$user->withGroups('create')->toArray();
103+
/*
104+
[
105+
'name' => '李四',
106+
'username' => 'username',
107+
'email' => 'zhangsan@example.com',
108+
]
109+
*/
110+
111+
$user->withGroups(['detail', 'other'])->toArray();
112+
/*
113+
[
114+
'id' => '1',
115+
'name' => '李四',
116+
'username' => 'username',
117+
'score' => 100,
118+
'email' => 'zhangsan@example.com',
119+
'sensitiveData' => '机密信息',
120+
]
121+
*/
149122
```
150123

151-
### 嵌套类指定Group类展示
124+
### 嵌套对象的分组
152125

153126
```php
154127
class ComplexUser extends Serialize {
155-
156128
public string $name;
157-
158129
public int $sex;
159-
160130
public ComplexNestedInfo $info;
161131
}
162132

163133
class ComplexNestedInfo extends Serialize {
164-
165-
#[Groups(ComplexAUser::class)]
134+
#[Groups(ComplexUser::class)]
166135
public float $money;
167136

168137
public string $currency;
169138
}
170-
171-
// ComplexNestedInfo 会自动隐藏currency
172-
$adminUser = ComplexUser::from(
173-
name: '张三',
174-
sex: 1,
175-
info: [
139+
php
140+
复制
141+
编辑
142+
$adminUser = ComplexUser::from([
143+
'name' => '张三',
144+
'sex' => 1,
145+
'info' => [
176146
'money' => 100.00,
177147
'currency' => 'CNY'
178-
];
179-
);
180-
181-
// 输出数据
182-
$adminUserArray = $adminUser->toArray();
183-
// $adminUserArray 的内容:
184-
// [
185-
// 'name' => '张三',
186-
// 'sex' => 1,
187-
// 'info' => ComplexNestedInfo Object ([
188-
// 'money' => 100.00
189-
// ])
190-
// ]
148+
],
149+
]);
150+
151+
// 默认输出包含所有字段
152+
$adminUser->toArray();
153+
/*
154+
[
155+
'name' => '张三',
156+
'sex' => 1,
157+
'info' => [
158+
'money' => 100.00
159+
]
160+
]
161+
*/
191162
```

0 commit comments

Comments
 (0)