Merge branch 'master' into featrue/open-api

Author: astral-data

README.md

@@ -24,6 +24,19 @@ It allows you to map objects to arrays/JSON and **automatically generate OpenAPI
 - 🧬 **Auto-generate OpenAPI schema** using object definitions
 - ⚙️ Framework-agnostic — works with Laravel, Symfony, etc.
 
+## Benchmark
+
+```bash
+    Run vendor/bin/phpbench run benchmarks/ --bootstrap=vendor/autoload.php
+    PHPBench (1.4.1) running benchmarks... #standwithukraine
+    with PHP version 8.4.8, xdebug ❌, opcache ❌
+
+    benchObjectCreation.....................I4 ✔ Mo117.841μs (±3.09%)
+    benchObjectCreationWithoutCache.........I4 ✔ Mo284.568μs (±0.71%)
+    benchObjectToArray......................I4 ✔ Mo62.883μs (±0.56%)
+    benchObjectToArrayWithoutCache..........I4 ✔ Mo211.700μs (±0.84%)
+```
+
 ## Quick Start
 
 ### Installation

docs/benchmark.png

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

docs/en/.gitbook.yaml

@@ -0,0 +1,16 @@
+# php-serialize
+
+**php-serialize** is a powerful attribute-based PHP serialization library (requires PHP ≥ 8.1).
+It allows you to map objects to arrays or JSON, and can automatically generate OpenAPI documentation based on the same
+
+> 🚀 Unified solution supporting API data serialization and document generation.
+
+## ✨ Features
+
+- 🏷️ Property alias mapping
+- 🔄 Automatic type conversion
+- 🔁 Support for deep object nesting
+- ❌ Support for skipping/excluding fields
+- 🧩 Recursive DTO (Data Transfer Object) serialization
+- 🧬 Automatically generate OpenAPI schema based on object definitions
+- ⚙️ Framework-agnostic — compatible with Laravel, Symfony, and more

docs/en/README.md

@@ -0,0 +1,36 @@
+# Summary
+
+* [Introduction](README.md)
+* [Getting Started](getting-started.md)
+
+## Attribute Conversion
+
+* [Basic Type Mapping](mapper/base-mapper.md)
+* [Null Value Mapping](mapper/null-mapper.md)
+* [Enum Mapping](mapper/enum-mapper.md)
+* [Array Object Mapping](mapper/array-mapper.md)
+* [Union Type Mapping](mapper/union-mapper.md)
+
+## Annotation Usage
+
+* [Attribute Grouping](annotation/group-annotation.md)
+* [Input/Output Mapping](annotation/alisa-annotation.md)
+* [Mapper Mapping](annotation/mapper-annotation.md)
+* [Input/Output Ignoring](annotation/ignore-annotation.md)
+* [Date Format Mapping](annotation/date-annotation.md)
+* [Custom Annotation](annotation/customer-annotation.md)
+
+## Parameter Mock Generation
+
+* [Simple Value Faker](faker/value-faker.md)
+* [Collection Faker](faker/collection-faker.md)
+* [Nested Faker](faker/nested-faker.md)
+* [Method Faker](faker/method-faker.md)
+
+## Automatic OpenAPI Documentation
+
+* [Basic Demo](openapi/base-openapi.md)
+* [Parameter Annotations](openapi/annotation.md)
+* [Override Annotations](openapi/override-annotation.md)
+* [Configuration](openapi/config.md)
+* [Launch Service](openapi/launch.md)

docs/en/SUMMARY.md

@@ -0,0 +1,141 @@
+## Name Mapping
+
+### Basic Usage
+
+```php
+use Astral\Serialize\Attributes\InputName;
+use Astral\Serialize\Attributes\OutputName;
+use Astral\Serialize\Serialize;
+
+class User extends Serialize {
+    // Use a different property name for input
+    #[InputName('user_name')]
+    public string $name;
+
+    // Use a different property name for output
+    #[OutputName('user_id')]
+    public int $id;
+
+    // Support different names for both input and output
+    #[InputName('register_time')]
+    #[OutputName('registeredAt')]
+    public DateTime $createdAt;
+}
+
+// Input data with different names
+$user = User::from([
+    'user_name' => 'Job',       // Mapped to $name
+    'id' => 123,                // Remains unchanged
+    'register_time' => '2023-01-01 10:00:00'  // Mapped to $createdAt
+]);
+
+// Output data
+$userArray = $user->toArray();
+// $userArray toArray:
+// [
+//     'name' => 'Job',
+//     'user_id' => 123,
+//     'registeredAt' => '2023-01-01 10:00:00'
+// ]
+```
+
+### Handling Multiple Input/Output Names
+
+```php
+use Astral\Serialize\Attributes\InputName;
+use Astral\Serialize\Attributes\OutputName;
+use Astral\Serialize\Serialize;
+
+class MultiOutputUser extends Serialize {
+    // output multiple names
+    #[OutputName('user_id')]
+    #[OutputName('id')]
+    #[OutputName('userId')]
+    public int $id;
+
+    // Multiple input names, the first matching name in declaration order will be used
+    #[InputName('user_name')]
+    #[InputName('other_name')]
+    #[InputName('userName')]
+    public int $name;
+
+}
+
+// Scenario 1: Use the first matching input name
+$user1 = MultiInputUser::from([
+    'user_name' => 'Job'  // Use 'user_name'
+]);
+echo $user1->name;  // Output 'Job'
+
+// Scenario 2: Use the second matching input name
+$user2 = MultiInputUser::from([
+    'other_name' => 'Tom'  // Use 'Tom'
+]);
+echo $user2->name;  // Output 'Tom'
+
+// Scenario 3: Use the last input name
+$user3 = MultiInputUser::from([
+    'userName' => 'Lin'  // Use 'userName'
+]);
+echo $user3->name;  // Output 'Lin'
+
+// Scenario 4: When multiple are passed, the first matching name in declaration order is used
+$user4 = MultiInputUser::from([
+    'userName' => 'Job',
+    'other_name' => 'Tom',
+    'user_name' => 'Lin',
+]);
+echo $user4->name;  // Output 'Job'
+
+// Create user object
+$user = MultiOutputUser::from([
+    'id' => 123,
+    'name' => 'Job'
+]);
+
+// Convert to array
+// tips: Since id has multiple output names, the output includes ['user_id','id','userId']
+$userArray = $user->toArray();
+// $userArray toArray:
+// [
+//     'user_id' => 123,
+//     'id' => 123,
+//     'userId' => 123,
+// ]
+```
+
+### Complex Mapping Scenarios
+
+```php
+use Astral\Serialize\Serialize;
+
+class ComplexUser extends Serialize {
+    // Name mapping for nested objects
+    #[InputName('user_profile')]
+    public UserProfile $profile;
+
+    // Name mapping for array elements
+    #[InputName('user_tags')]
+    public array $tags;
+}
+
+// Handle complex input structure
+$complexUser = ComplexUser::from([
+    'user_profile' => [
+        'nickname' => 'job',
+        'age' => 25
+    ],
+    'user_tags' => ['developer', 'programmer']
+]);
+
+// Convert to standard array
+$complexUserArray = $complexUser->toArray();
+// $complexUserArray toArray:
+// [
+//     'profile' => UserProfile Object ([
+//         'nickname' => 'job',
+//         'age' => 25
+//     ]),
+//     'tags' => ['developer', 'programmer']
+// ]
+```

docs/en/annotation/alisa-annotation.md

@@ -0,0 +1,73 @@
+### Custom Annotation Class Implementation
+
+You can flexibly extend the input/output handling logic of the serialization library by defining custom annotation classes.
+
+---
+
+#### Input Processing Annotation Class
+
+Implement the `InputValueCastInterface` interface, and override its `match` and `resolve` methods to customize the conversion and handling of input data.
+
+- **`match`**: Used to determine whether to process the current value; returning `true` means `resolve` will be called.
+- **`resolve`**: Converts the matched input value and returns the result.
+
+Example: Annotation class that adds a custom prefix to the input value
+
+```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
+    {
+        // Applies to all input values
+        return true;
+    }
+
+    public function resolve(mixed $value, DataCollection $collection, InputValueContext $context): mixed
+    {
+        // Add prefix to input value
+        return $this->prefix . $value;
+    }
+}
+```
+
+### Output Processing Annotation Class
+
+The output processing annotation is similar to the input processing annotation, but implements a different interface—`OutputValueCastInterface`, which is used to customize the conversion of serialized output values.
+
+Example: Annotation class that adds a custom suffix to the serialized output value
+
+```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
+    {
+        // Applies to all output values
+        return true;
+    }
+
+    public function resolve(mixed $value, DataCollection $collection, OutputValueContext $context): mixed
+    {
+        // Add suffix to output value
+        return $value . $this->suffix;
+    }
+}
+```
+

docs/en/annotation/customer-annotation.md

@@ -0,0 +1,92 @@
+## Date/Time Conversion
+
+1. Flexible Formatting
+   Supports multiple input and output date/time formats
+   Easily handles date representations from different regions
+2. Timezone Handling
+   Supports conversion between different timezones
+   Automatically handles timezone offsets for times
+3. Type Safety
+   Automatically converts strings to DateTime objects
+   Ensures type consistency and correctness
+
+### Basic Usage
+
+```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;
+
+    // Output date format conversion
+    #[OutputDateFormat('Y/m/d H:i')]
+    public DateTime|string $processedAt;
+    
+
+    // Supports multiple date/time formats
+    #[InputDateFormat('Y-m-d H:i:s')]
+    #[OutputDateFormat('Y-m-d')]
+    public string $createdAt;
+}
+
+// Create order object
+$order = TimeExample::from([
+    'dateTime' => new DateTime('2023-08-11'),           // Input format: Y-m-d
+    'dateDateString' => '2023-08-15',           // Input format: Y-m-d
+    'processedAt' => '2023-08-16 14:30',   // Default input format, also supports DateTime objects
+    'createdAt' => '2023-08-16 14:45:30'   // Input format: Y-m-d H:i:s
+]);
+
+// Convert to array
+$orderArray = $order->toArray();
+// Content of $orderArray:
+// [
+//     'dateTime' => '2023-08-11',
+//     'dateDateString' => '2023-08-15',
+//     'processedAt' => '2023/08/16 14:30',
+//     'createdAt' => '2023-08-16'
+// ]
+```
+
+### Time Conversion with Timezone
+
+```php
+
+use Astral\Serialize\Attributes\Input\InputDateFormat;
+use Astral\Serialize\Attributes\Output\OutputDateFormat;
+use Astral\Serialize\Serialize;
+
+class AdvancedTimeUser extends Serialize {
+    // Supports timezone conversion
+    #[InputDateFormat('Y-m-d H:i:s', timezone: 'UTC')]
+    #[OutputDateFormat('Y-m-d H:i:s', timezone: 'Asia/Shanghai')]
+    public DateTime $registeredAt;
+
+    // Supports date formats from different regions
+    #[InputDateFormat('d/m/Y')]  // UK format
+    #[OutputDateFormat('Y-m-d')]  // Standard format
+    public DateTime $birthDate;
+}
+
+// Use advanced time conversion
+$advancedUser = AdvancedTimeUser::from([
+    'registeredAt' => '2023-08-16 10:00:00',  // UTC time
+    'birthDate' => '15/08/1990'  // UK date format
+]);
+
+$advancedUserArray = $advancedUser->toArray();
+// Content of $advancedUserArray:
+// [
+//     'registeredAt' => '2023-08-16 18:00:00',  // Converted to Shanghai timezone
+//     'birthDate' => '1990-08-15'
+// ]
+```