docs: rewrite JsonRpcBundle docs, add SDK docs, move them under docs/api
en/docs/api/json-rpc-bundle/add_rpc_service/response/README.md
new file +85
ā0
1
+
# Response format
2
+
3
+
The result schema in the [documentation](/docs/api/json-rpc-bundle/documentation) is built automatically from the type the method returns. A separate attribute is needed only when the type cannot be inferred from the signature.
4
+
5
+
## Scalar types
6
+
7
+
For `string`, `int`, `float`, `bool`, nullable and union types, the schema is taken from the native return type.
8
+
9
+
```php
10
+
public function ping(): string
11
+
```
12
+
13
+
## Arrays: type from PHPDoc
14
+
15
+
For `array`, the exact type is specified in `@return`. It takes precedence over the native type.
16
+
17
+
```php
18
+
/**
19
+
* @return array<string, int>
20
+
*/
21
+
public function stats(): array
22
+
```
23
+
24
+
## DTO
25
+
26
+
If a method returns a class (or an array of a class in `@return`), that class becomes the result format: a DTO schema with all its properties appears in OpenRPC, and the object is serialized into the response.
27
+
28
+
```php
29
+
final class UserDto
30
+
{
31
+
public function __construct(
32
+
public int $id,
33
+
public string $email,
34
+
public ?string $name = null,
35
+
) {}
36
+
}
37
+
38
+
public function get(int $id): UserDto
39
+
40
+
/**
41
+
* @return UserDto[]
42
+
*/
43
+
public function list(): array
44
+
```
45
+
46
+
::::columns
47
+
:::col
48
+
**Request**
49
+
```json
50
+
{"jsonrpc": "2.0", "id": 1, "method": "User.get", "params": {"id": 5}}
51
+
```
52
+
:::
53
+
:::col
54
+
**Response**
55
+
```json
56
+
{
57
+
"jsonrpc": "2.0",
58
+
"id": 1,
59
+
"result": {"id": 5, "email": "user@example.com", "name": null}
60
+
}
61
+
```
62
+
:::
63
+
::::
64
+
65
+
DTO property types are taken from native types and PHPDoc (`@var`, constructor `@param` for promoted properties). Properties that have a [converter](/docs/api/json-rpc-bundle/add_rpc_service/params) (enum, date, UUID, Doctrine entity) are converted to scalars in the response.
66
+
67
+
## `#[RPC\DTO]`
68
+
69
+
When a method returns `array` or `object` but the format is known, specify it with an attribute on the method:
70
+
71
+
```php
72
+
use Ufo\RpcObject\RPC;
73
+
74
+
#[RPC\DTO(UserDto::class)]
75
+
public function getRaw(int $id): array
76
+
77
+
#[RPC\DTO(UserDto::class, collection: true)]
78
+
public function listRaw(): array
79
+
```
80
+
81
+
Signature: `DTO(string $dtoFQCN, bool $collection = false, array $context = [])`. For a collection on a method, use `collection: true`: `#[RPC\DTOCollection]` on a method is currently not read (see [Open issues](/docs/api/json-rpc-bundle/developers/known_issues/open)). The attribute also works on DTO properties to set the type of nested objects and collections.
82
+
83
+
:::info subtitle="Migrating from older versions"
84
+
`#[RPC\Response]` is not read since version 7.6, and `#[RPC\ResultAsDTO]` has been replaced by `#[RPC\DTO]`. The description for older versions is available in the version selector at the top of the page.
85
+
:::