add en doc

Author: astral-data

docs/en/.gitbook.yaml

@@ -0,0 +1,4 @@
+root: ./
+structure:
+  readme: README.md
+  summary: SUMMARY.md

docs/en/README.md

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

docs/en/SUMMARY.md

@@ -0,0 +1,36 @@
+# Summary
+
+* [介绍](README.md)
+* [快速开始](getting-started.md)
+
+## 属性转换
+
+* [基本类型转换](mapper/base-mapper.md)
+* [Null值转换](mapper/null-mapper.md)
+* [枚举转换](mapper/enum-mapper.md)
+* [数组对象转换](mapper/array-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)
+* [自定义注解](annotation/customer-annotation.md)
+
+## 参数快速模拟生成
+
+* [简单属性Faker](faker/value-faker.md)
+* [集合Faker](faker/collection-faker.md)
+* [嵌套Faker](faker/nested-faker.md)
+* [方法Faker](faker/method-faker.md)
+
+## 自动创建OpenApi文档
+
+* [基础演示](openapi/base-openapi.md)
+* [参数注解](openapi/annotation.md)
+* [重写注解](openapi/override-annotation.md)
+* [配置](openapi/config.md)
+* [启动服务](openapi/launch.md)

docs/en/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/en/annotation/customer-annotation.md

@@ -0,0 +1,73 @@
+### 自定义注解类实现
+
+你可以通过自定义注解类，灵活地扩展序列化库的输入输出处理逻辑。
+
+---
+
+#### 入参处理注解类
+
+实现 `InputValueCastInterface` 接口，重写其中的 `match` 和 `resolve` 方法，来自定义输入数据的转换和处理。
+
+- **`match`**：用于判断是否对当前值进行处理，返回 `true` 表示进入 `resolve`。
+- **`resolve`**：对匹配的输入值进行转换，并返回转换后的结果。
+
+示例：给输入值添加自定义前缀的注解类
+
+```php
+use Astral\Serialize\Contracts\Attribute\InputValueCastInterface;
+use Attribute;
+
+#[Attribute(Attribute::TARGET_PROPERTY | Attribute::TARGET_CLASS)]
+class CustomerInput implements InputValueCastInterface
+{
+    public function __construct(
+        public string $prefix = '',
+    ) {
+    }
+    
+    public function match(mixed $value, DataCollection $collection, InputValueContext $context): bool
+    {
+        // 对所有输入值都生效
+        return true;
+    }
+
+    public function resolve(mixed $value, DataCollection $collection, InputValueContext $context): mixed
+    {
+        // 给输入值添加前缀
+        return $this->prefix . $value;
+    }
+}
+````
+
+### 输出处理注解类
+
+输出处理注解与输入处理注解类似，只是实现的接口不同——需要实现 `OutputValueCastInterface`，用以对序列化输出的值进行自定义转换。
+
+示例：给序列化输出的值添加自定义后缀的注解类
+
+```php
+use Astral\Serialize\Contracts\Attribute\OutputValueCastInterface;
+use Attribute;
+
+#[Attribute(Attribute::TARGET_PROPERTY | Attribute::TARGET_CLASS)]
+class CustomerOutput implements OutputValueCastInterface
+{
+    public function __construct(
+        public string $suffix = '',
+    ) {
+    }
+    
+    public function match(mixed $value, DataCollection $collection, OutputValueContext $context): bool
+    {
+        // 对所有输出值都生效
+        return true;
+    }
+
+    public function resolve(mixed $value, DataCollection $collection, OutputValueContext $context): mixed
+    {
+        // 给输出值添加后缀
+        return $value . $this->suffix;
+    }
+}
+```
+

docs/en/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'
+// ]
+```