diff --git a/.openapi.php b/.openapi.php index 302fb95..49bd55b 100644 --- a/.openapi.php +++ b/.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', ] ]; diff --git a/docs/en/SUMMARY.md b/docs/en/SUMMARY.md index 6710302..4dd73b3 100644 --- a/docs/en/SUMMARY.md +++ b/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 diff --git a/docs/en/mapper/out.md b/docs/en/mapper/out.md new file mode 100644 index 0000000..2e4c2cc --- /dev/null +++ b/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"} +``` \ No newline at end of file diff --git a/docs/en/openapi/config.md b/docs/en/openapi/config.md index c5f2b94..093493a 100644 --- a/docs/en/openapi/config.md +++ b/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', ] ]; diff --git a/docs/zh/SUMMARY.md b/docs/zh/SUMMARY.md index 3d2b495..0beb677 100644 --- a/docs/zh/SUMMARY.md +++ b/docs/zh/SUMMARY.md @@ -10,6 +10,7 @@ * [枚举转换](mapper/enum-mapper.md) * [数组对象转换](mapper/array-mapper.md) * [联合类型转换](mapper/union-mapper.md) +* [输出格式](mapper/out.md) ## 注解类使用 diff --git a/docs/zh/mapper/out.md b/docs/zh/mapper/out.md new file mode 100644 index 0000000..e8fcf15 --- /dev/null +++ b/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"} +``` \ No newline at end of file diff --git a/docs/zh/openapi/config.md b/docs/zh/openapi/config.md index 68a099c..259f886 100644 --- a/docs/zh/openapi/config.md +++ b/docs/zh/openapi/config.md @@ -69,7 +69,7 @@ return [ */ 'response' => [ 'code' => ['description' =>'状态码', 'example'=> 200], - 'message' => ['description' =>'返回信息', 'example'=> '操作成功'], + 'message' => ['description' =>'返回信息', 'example'=> 'success'], 'data' => 'T', ] ]; diff --git a/tests/Serialize/Config/AddCastTest.php b/tests/Serialize/Config/AddCastTest.php index fb34ce3..3ace6cf 100644 --- a/tests/Serialize/Config/AddCastTest.php +++ b/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')] diff --git a/tests/Serialize/From/NormalizerFromSerializeTest.php b/tests/Serialize/From/NormalizerFromSerializeTest.php index b83d09e..0d8f0b0 100644 --- a/tests/Serialize/From/NormalizerFromSerializeTest.php +++ b/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);