gitbook test

Author: astral-data

docs/zh/SUMMARY.md

@@ -11,4 +11,19 @@
 * [Null值转换](mapper/null-mapper.md)
 * [枚举转换](mapper/enum-mapper.md)
 * [数组对象转换](mapper/array-mapper.md)
-* [联合类型转换](mapper/union-mapper.md)
+* [联合类型转换](mapper/union-mapper.md)
+
+## 注解类使用
+
+* [属性分组](annotation/group-annotation.md)
+* [输入/输入出名称映射](annotation/alisa-annotation.md)
+* [Mapper映射](annotation/mapper-annotation.md)
+* [输入/输出忽略](annotation/ignore-annotation.md)
+* [时间格式映射](annotation/date-annotation.md)
+
+## 参数快速Faker
+
+* [简单属性Faker](faker/value-faker.md)
+* [集合Faker](faker/collection-faker.md)
+* [嵌套Faker](faker/nested-faker.md)
+* [方法Faker](faker/method-faker.md)

docs/zh/annotation/alisa-annotation.md

@@ -0,0 +1,141 @@
+#### 名称映射
+
+##### 基础使用
+
+```php
+use Astral\Serialize\Attributes\InputName;
+use Astral\Serialize\Attributes\OutputName;
+use Astral\Serialize\Serialize;
+
+class User extends Serialize {
+    // 输入时使用不同的属性名
+    #[InputName('user_name')]
+    public string $name;
+
+    // 输出时使用不同的属性名
+    #[OutputName('user_id')]
+    public int $id;
+
+    // 同时支持输入和输出不同名称
+    #[InputName('register_time')]
+    #[OutputName('registeredAt')]
+    public DateTime $createdAt;
+}
+
+// 使用不同名称的输入数据
+$user = User::from([
+    'user_name' => '张三',       // 映射到 $name
+    'id' => 123,                // 保持不变
+    'register_time' => '2023-01-01 10:00:00'  // 映射到 $createdAt
+]);
+
+// 输出数据
+$userArray = $user->toArray();
+// $userArray 的内容:
+// [
+//     'name' => '张三',
+//     'user_id' => 123,
+//     'registeredAt' => '2023-01-01 10:00:00'
+// ]
+```
+
+##### 多输入/输出名称处理
+
+```php
+use Astral\Serialize\Attributes\InputName;
+use Astral\Serialize\Attributes\OutputName;
+use Astral\Serialize\Serialize;
+
+class MultiOutputUser extends Serialize {
+    // 多个输出名称
+    #[OutputName('user_id')]
+    #[OutputName('id')]
+    #[OutputName('userId')]
+    public int $id;
+
+    // 多个输出名称 按照声明顺序取地一个匹配的name
+    #[InputName('user_name')]
+    #[InputName('other_name')]
+    #[InputName('userName')]
+    public int $name;
+
+}
+
+// 场景1：使用第一个匹配的输入名称
+$user1 = MultiInputUser::from([
+    'user_name' => '张三'  // 使用 'user_name'
+]);
+echo $user1->name;  // 输出 '张三'
+
+// 场景2：使用第二个匹配的输入名称
+$user2 = MultiInputUser::from([
+    'other_name' => '李四'  // 使用 'other_name'
+]);
+echo $user2->name;  // 输出 '李四'
+
+// 场景3：使用最后的输入名称
+$user3 = MultiInputUser::from([
+    'userName' => '王五'  // 使用 'userName'
+]);
+echo $user3->name;  // 输出 '王五'
+
+// 场景4：传入多个的时候 按照声明顺序取地一个匹配的name
+$user4 = MultiInputUser::from([
+    'userName' => '王五',
+    'other_name' => '李四',
+    'user_name' => '张三',
+]);
+echo $user4->name;  // 输出 '张三'
+
+// 创建用户对象
+$user = MultiOutputUser::from([
+    'id' => 123,
+    'name' => '张三'
+]);
+
+// 转换为数组
+// tips: 因为id 有多个outputname 所以输出了 ['user_id','id','userId']
+$userArray = $user->toArray();
+// $userArray 的内容:
+// [
+//     'user_id' => 123,
+//     'id' => 123,
+//     'userId' => 123,
+// ]
+```
+
+##### 复杂映射场景
+
+```php
+use Astral\Serialize\Serialize;
+
+class ComplexUser extends Serialize {
+    // 嵌套对象的名称映射
+    #[InputName('user_profile')]
+    public UserProfile $profile;
+
+    // 数组元素的名称映射
+    #[InputName('user_tags')]
+    public array $tags;
+}
+
+// 处理复杂的输入结构
+$complexUser = ComplexUser::from([
+    'user_profile' => [
+        'nickname' => '小明',
+        'age' => 25
+    ],
+    'user_tags' => ['developer', 'programmer']
+]);
+
+// 转换为标准数组
+$complexUserArray = $complexUser->toArray();
+// $complexUserArray 的内容:
+// [
+//     'profile' => UserProfile Object ([
+//         'nickname' => '小明',
+//         'age' => 25
+//     ]),
+//     'tags' => ['developer', 'programmer']
+// ]
+```

docs/zh/annotation/date-annotation.md

@@ -0,0 +1,92 @@
+#### 时间转换
+
+1. 格式灵活性
+   支持多种输入和输出时间格式
+   可以轻松处理不同地区的日期表示
+2. 时区处理
+   支持在不同时区间转换
+   自动处理时间的时区偏移
+3. 类型安全
+   自动将字符串转换为 DateTime 对象
+   保证类型的一致性和正确性
+
+##### 基础使用
+
+```php
+use Astral\Serialize\Attributes\Input\InputDateFormat;
+use Astral\Serialize\Attributes\Output\OutputDateFormat;
+use Astral\Serialize\Serialize;
+
+class TimeExample extends Serialize {
+
+    // 输入时间格式转换
+    #[InputDateFormat('Y-m-d')]
+    public DateTime $dateTime;
+
+    // 输入时间格式转换
+    #[InputDateFormat('Y-m-d')]
+    public string $dateDateString;
+
+    // 输出时间格式转换
+    #[OutputDateFormat('Y/m/d H:i')]
+    public DateTime|string $processedAt;
+    
+
+    // 支持多种时间格式
+    #[InputDateFormat('Y-m-d H:i:s')]
+    #[OutputDateFormat('Y-m-d')]
+    public string $createdAt;
+}
+
+// 创建订单对象
+$order = TimeExample::from([
+    'dateTime' => new DateTime('2023-08-11'),           // 输入格式：Y-m-d
+    'dateDateString' => '2023-08-15',           // 输入格式：Y-m-d
+    'processedAt' => '2023-08-16 14:30',   // 输入默认格式 也支持DateTime对象
+    'createdAt' => '2023-08-16 14:45:30'   // 输入格式：Y-m-d H:i:s
+]);
+
+// 转换为数组
+$orderArray = $order->toArray();
+// $orderArray 的内容:
+// [
+//     'dateTime' => '2023-08-11',
+//     ’dateDateString' => '2023-08-15',
+//     'processedAt' => '2023/08/16 14:30',
+//     'createdAt' => '2023-08-16'
+// ]
+```
+
+##### 带时区的时间转换
+
+```php
+
+use Astral\Serialize\Attributes\Input\InputDateFormat;
+use Astral\Serialize\Attributes\Output\OutputDateFormat;
+use Astral\Serialize\Serialize;
+
+class AdvancedTimeUser extends Serialize {
+    // 支持时区转换
+    #[InputDateFormat('Y-m-d H:i:s', timezone: 'UTC')]
+    #[OutputDateFormat('Y-m-d H:i:s', timezone: 'Asia/Shanghai')]
+    public DateTime $registeredAt;
+
+    // 支持不同地区的时间格式
+    #[InputDateFormat('d/m/Y')]  // 英国格式
+    #[OutputDateFormat('Y-m-d')]  // 标准格式
+    public DateTime $birthDate;
+}
+
+// 使用高级时间转换
+$advancedUser = AdvancedTimeUser::from([
+    'registeredAt' => '2023-08-16 10:00:00',  // UTC 时间
+    'birthDate' => '15/08/1990'  // 英国日期格式
+]);
+
+$advancedUserArray = $advancedUser->toArray();
+// $advancedUserArray 的内容:
+// [
+//     'registeredAt' => '2023-08-16 18:00:00',  // 转换为上海时区
+//     'birthDate' => '1990-08-15'
+// ]
+```