docs: rewrite JsonRpcBundle docs, add SDK docs, move them under docs/api
uk/docs/api/json-rpc-bundle/add_rpc_service/response/README.md
новий файл +85
−0
1
+
# Формат відповіді
2
+
3
+
Схема результату в [документації](/docs/api/json-rpc-bundle/documentation) будується автоматично з типу, який повертає метод. Окремий атрибут потрібен лише тоді, коли тип не можна вивести з сигнатури.
4
+
5
+
## Скалярні типи
6
+
7
+
Для `string`, `int`, `float`, `bool`, nullable- і union-типів схема береться з нативного типу повернення.
8
+
9
+
```php
10
+
public function ping(): string
11
+
```
12
+
13
+
## Масиви: тип з PHPDoc
14
+
15
+
Для `array` точний тип вказується в `@return`. Він має пріоритет над нативним типом.
16
+
17
+
```php
18
+
/**
19
+
* @return array<string, int>
20
+
*/
21
+
public function stats(): array
22
+
```
23
+
24
+
## DTO
25
+
26
+
Якщо метод повертає клас (або масив класу в `@return`), цей клас стає форматом результату: в OpenRPC з'являється схема DTO з усіма властивостями, а об'єкт серіалізується у відповідь.
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 беруться з нативних типів і PHPDoc (`@var`, `@param` конструктора для promoted-властивостей). Властивості, для яких є [конвертор](/docs/api/json-rpc-bundle/add_rpc_service/params) (enum, дата, UUID, сутність Doctrine), у відповіді перетворюються на скаляри.
66
+
67
+
## `#[RPC\DTO]`
68
+
69
+
Коли метод повертає `array` або `object`, а формат відомий, вкажіть його атрибутом на методі:
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
+
Сигнатура: `DTO(string $dtoFQCN, bool $collection = false, array $context = [])`. Для колекції на методі використовуйте саме `collection: true`: `#[RPC\DTOCollection]` на методі зараз не зчитується (див. [Актуальні помилки](/docs/api/json-rpc-bundle/developers/known_issues/open)). Атрибут також працює на властивостях DTO, щоб задати тип вкладених об'єктів і колекцій.
82
+
83
+
:::info subtitle="Міграція зі старих версій"
84
+
`#[RPC\Response]` не зчитується з версії 7.6, а `#[RPC\ResultAsDTO]` замінено на `#[RPC\DTO]`. Опис для старих версій — у перемикачі версій угорі сторінки.
85
+
:::