Featrue/normalizers

.openapi.php

@@ -57,8 +57,8 @@
      *
      */
     'response' => [
-        'code' => ['description' =>'状态码', 'example'=> 200],
-        'message' => ['description' =>'返回信息', 'example'=> '操作成功'],
+        'code' => ['description' =>'code', 'example'=> 200],
+        'message' => ['description' =>'message', 'example'=> 'success'],
         'data' => 'T',
     ]
 ];

docs/en/SUMMARY.md

@@ -10,6 +10,7 @@
 * [Enum Mapping](mapper/enum-mapper.md)
 * [Array Object Mapping](mapper/array-mapper.md)
 * [Union Type Mapping](mapper/union-mapper.md)
+* [Output Format](mapper/out.md)
 
 ## Annotation Usage
 

docs/en/mapper/out.md

@@ -0,0 +1,109 @@
+## Output Format
+
+### Creating the Serialize Class
+
+```php
+use Astral\Serialize\Serialize;
+use DateTime;
+
+class UserLoginLog extends Serialize {
+    public string $remark,
+    public DateTime $create_time;
+}
+
+class User extends Serialize {
+    public string $name,
+    public int $age,
+    public UserLoginLog $login_log
+}
+
+// Create an object
+$user = User::from([
+    'name' => 'Jon',
+    'age' => 30
+], login_log: new UserLoginLog(remark:'Test Data',create_time: DateTime::createFromFormat('Y-m-d','2008-09-01')));
+````
+
+### Outputting the Object
+
+```php
+// $user is an object by default
+echo $user->name;  // Output: Jon
+echo $user->age;   // Output: 30
+echo $user->login_log->remark; // Output 'Test Data'
+echo $user->login_log->create_time; // Output DateTime Object
+
+```
+
+### Outputting an Array
+
+```php
+// Convert to an array
+$vols = $user->toArray();
+echo $vols['name'];  // Output: Jon
+echo $vols['age'];   // Output: 30
+echo $vols['login_log']['remark']; // Output 'Test Data'
+echo $vols['login_log']['create_time']; // Output 2008-09-01 00:00:00
+// Content of $vols:
+// [
+//     'name' => 'Jon',
+//     'age' => 30,
+//     'login_log' => [
+//         [
+//              'remark' => 'Test Data',
+//              'create_time' => '2008-09-01 00:00:00'
+//          ]
+//     ]
+// ]
+```
+
+### Outputting a JSON String
+
+1. The `Serialize` class implements `JsonSerializable` by default. Similar to a `Laravel` `Controller` you can directly return the object, and the framework will output the `JSON` information correctly
+2. By default, the JSON output from `Serialize` includes `data` `code` and  `message` f you need to [replace/modify/add] these, please refer to the configuration information [Response Data Structure Definition](../openapi/config.md)
+
+#### Outputting JSON Information
+
+- You can use the API `toJsonString` 
+- Alternatively, you can directly use `json_decode`
+
+```php
+echo $user->toJsonString();
+echo json_decode($user);
+// Both outputs are the same
+// {"code":200,"message":"success","data":{"name":"Jon","age":30,"login_log":{"remark":"Test Data","create_time":"2008-09-01 00:00:00"}}
+```
+
+#### Setting Output Code/Message
+
+```php
+$user->setCode(500);
+$user->setMessage('Operation failed');
+echo json_decode($user);
+// Output
+// {"code":500,"message":"Operation failed","data":{"name":"Jon","age":30,"login_log":{"remark":"Test Data","create_time":"2008-09-01 00:00:00"}}
+```
+
+#### Setting Custom JSON Outer Layer
+
+`withResponses` can temporarily add or modify custom return information. To add global return information, you can configure it in the [Response Data Structure Definition](../openapi/config.md)
+
+```php
+$user->withResponses([
+        "code"=> ["description"=>"Return Code", "value"=>401],
+        "message"=> ["description"=>"Return Message", "value"=>"Operation successful"],
+        "error"=> ["description"=>"Return Error", "value"=>0],
+]);
+// Output
+// {"code":401,"message":"Operation successful","error":0,"data":{"name":"Jon","age":30,"login_log":{"remark":"Test Data","create_time":"2008-09-01 00:00:00"}}
+```
+
+#### Outputting JSON Without Outer Layer Information
+
+Use`withoutResponseToJsonString` to return JSON data containing only the object’s properties.
+
+```php
+$user->withoutResponseToJsonString();
+// Output
+// {"name":"Jon","age":30,"login_log":{"remark":"Test Data","create_time":"2008-09-01 00:00:00"}
+```

docs/en/openapi/config.md

@@ -68,8 +68,8 @@ return [
      *
      */
     'response' => [
-        'code' => ['description' =>'状态码', 'example'=> 200],
-        'message' => ['description' =>'返回信息', 'example'=> '操作成功'],
+        'code' => ['description' =>'code', 'example'=> 200],
+        'message' => ['description' =>'message', 'example'=> 'success'],
         'data' => 'T',
     ]
 ];

docs/zh/SUMMARY.md

@@ -10,6 +10,7 @@
 * [枚举转换](mapper/enum-mapper.md)
 * [数组对象转换](mapper/array-mapper.md)
 * [联合类型转换](mapper/union-mapper.md)
+* [输出格式](mapper/out.md)
 
 ## 注解类使用
 

docs/zh/mapper/out.md

@@ -0,0 +1,110 @@
+## 输出格式
+
+### 创建Serialize类
+
+```php
+use Astral\Serialize\Serialize;
+use DateTime;
+
+class UserLoginLog extends Serialize {
+    public string $remark,
+    public DateTime $create_time;
+}
+
+class User extends Serialize {
+    public string $name,
+    public int $age,
+    public UserLoginLog $login_log
+}
+
+// 创建对象
+$user = User::from([
+    'name' => '张三',
+    'age' => 30
+], login_log: new UserLoginLog(remark:'测试数据',create_time: DateTime::createFromFormat('Y-m-d','2008-09-01')));
+````
+
+### 输出对象
+
+```php
+// $user默认就是一个对象
+echo $user->name;  // 输出: 张三
+echo $user->age;   // 输出: 30
+echo $user->login_log->remark; // 输出 '测试数据'
+echo $user->login_log->create_time; // 输出 DateTime对象
+
+```
+
+### 输出数组
+
+```php
+// 转换成数组
+$vols = $user->toArray();
+echo $vols['name'];  // 输出: 张三
+echo $vols['age'];   // 输出: 30
+echo $vols['login_log']['remark']; // 输出 '测试数据'
+echo $vols['login_log']['create_time']; // 输出 2008-09-01 00:00:00
+// $vols 的内容:
+// [
+//     'name' => '张三',
+//     'age' => 30,
+//     'login_log' => [
+//         [
+//              'remark' => '测试数据',
+//              'create_time' => '2008-09-01 00:00:00'
+//          ]
+//     ]
+// ]
+```
+
+### 输出数组json字符串
+
+1. `Serialize` 默认实现了 `JsonSerializable` 类似`Laravel`的`Controller` 可以直接返回对象，框架会正常输出`json信息`
+2. `Serialize` 默认json 增加 `data` `code` `message` 如果需要`[替换/修改/增加]`
+请查看配置信息 [响应数据结构定义](../openapi/config.md)
+
+#### 输出json信息
+
+- 可以使用 api `toJsonString` 
+- 也可以直接使用 `json_decode`
+
+```php
+echo $user->toJsonString();
+echo json_decode($user);
+// 输出内容相同
+// {"code":200,"message":"success","data":{"name":"张三","age":30,"login_log":{"remark":"测试数据","create_time":"2008-09-01 00:00:00"}}
+```
+
+#### 设置输出code/message
+
+```php
+$user->setCode(500);
+$user->setMessage('操作失败');
+echo json_decode($user);
+// 输出内容
+// {"code":500,"message":"操作失败","data":{"name":"张三","age":30,"login_log":{"remark":"测试数据","create_time":"2008-09-01 00:00:00"}}
+```
+
+#### 设置自定义json外层
+
+`withResponses` 可以临时增加修改自定义返回信息,全局增加返回信息可以在 [响应数据结构定义](../openapi/config.md)中配置
+
+```php
+$user->withResponses([
+        "code"=> ["description"=>"返回code", "value"=>401],
+        "message"=> ["description"=>"返回信息", "value"=>"操作成功"],
+        "error"=> ["description"=>"返回error", "value"=>0],
+]);
+// 输出内容
+// {"code":401,"message":"操作成功","error":0,"data":{"name":"张三","age":30,"login_log":{"remark":"测试数据","create_time":"2008-09-01 00:00:00"}}
+```
+
+#### 输出不包含外层信息的Json
+
+使用`withoutResponseToJsonString` 可以返回只有对象属性的json数据
+
+```php
+$user->withoutResponseToJsonString();
+// 输出内容
+// {"name":"张三","age":30,"login_log":{"remark":"测试数据","create_time":"2008-09-01 00:00:00"}
+```

docs/zh/openapi/config.md

@@ -69,7 +69,7 @@ return [
      */
     'response' => [
         'code' => ['description' =>'状态码', 'example'=> 200],
-        'message' => ['description' =>'返回信息', 'example'=> '操作成功'],
+        'message' => ['description' =>'返回信息', 'example'=> 'success'],
         'data' => 'T',
     ]
 ];

tests/Serialize/Config/AddCastTest.php

@@ -8,8 +8,6 @@
 use Astral\Serialize\Support\Config\ConfigManager;
 
 beforeAll(function () {
-
-
     class AddCastTestClass extends Serialize
     {
         #[InputName('name_three_other')]

tests/Serialize/From/NormalizerFromSerializeTest.php

@@ -69,7 +69,7 @@ class NormalizerClass extends Serialize
     $res = NormalizerClass::from(one: $normalizerOne, two: $normalizerTwo, three: $normalizerOne);
 
     $resJson = json_encode($res);
-    expect($resJson)->toBe('{"code":200,"message":"\u64cd\u4f5c\u6210\u529f","data":{"one":{"name_one":"one name","id_one":1},"two":{"name_two":"two name","id_2":2},"three":{"name_one":"one name","id_one":1}}}');
+    expect($resJson)->toBe('{"code":200,"message":"success","data":{"one":{"name_one":"one name","id_one":1},"two":{"name_two":"two name","id_2":2},"three":{"name_one":"one name","id_one":1}}}');
 
     $res->setMessage('233');
     $resJson = json_encode($res);