docs: rewrite JsonRpcBundle docs, add SDK docs, move them under docs/api
uk/docs/api/json-rpc-bundle/add_rpc_service/params.md
новий файл +152
−0
1
+
# Параметри методів
2
+
3
+
Параметри RPC-методу — це параметри PHP-методу. Бандл бере їхні назви, типи й значення за замовчуванням із сигнатури та PHPDoc, будує з них JSON Schema для [документації](/docs/api/json-rpc-bundle/documentation) і перед викликом перетворює вхідні значення на потрібні типи.
4
+
5
+
## Скалярні типи
6
+
7
+
`string`, `int`, `float`, `bool`, `array`, `mixed` та їхні nullable/union-варіанти передаються як є. Параметр зі значенням за замовчуванням (зокрема `null`) необов'язковий.
8
+
9
+
```php
10
+
public function search(string $query, int $limit = 20, ?string $sort = null): array
11
+
```
12
+
13
+
Неправильний тип чи відсутній обов'язковий параметр повертає помилку `-32602` з переліком проблем по кожному параметру — див. [Обробка помилок](/docs/api/json-rpc-bundle/error_handling).
14
+
15
+
## Точні типи з PHPDoc
16
+
17
+
Якщо нативного типу недостатньо (`array`), точний тип береться з `@param`. Імена класів розв'язуються через `use`-імпорти класу процедури.
18
+
19
+
```php
20
+
/**
21
+
* @param OrderItemDto[] $items
22
+
* @param array<string, int|string> $meta
23
+
*/
24
+
public function save(array $items, array $meta = []): bool
25
+
```
26
+
27
+
## DTO
28
+
29
+
Параметр, тип якого — клас, автоматично створюється з JSON-об'єкта:
30
+
31
+
```php
32
+
final class CreateOrderDto
33
+
{
34
+
public function __construct(
35
+
public string $sku,
36
+
public int $qty = 1,
37
+
) {}
38
+
}
39
+
40
+
public function create(CreateOrderDto $order): int
41
+
```
42
+
43
+
```json
44
+
{"jsonrpc": "2.0", "id": 1, "method": "Order.create", "params": {"order": {"sku": "A-1", "qty": 2}}}
45
+
```
46
+
47
+
* Колекція DTO описується в PHPDoc (`@param CreateOrderDto[] $orders`) — кожен елемент масиву стає об'єктом.
48
+
* Для union-типів (`FooDto|BarDto`) береться перший DTO, який вдалося створити.
49
+
* Значення, з якого не вдається створити DTO, повертає помилку валідації, а не сирий масив.
50
+
* У схемі DTO властивості зі значенням за замовчуванням отримують `default`, а в `required` потрапляють лише властивості без нього.
51
+
52
+
## Автоматична конвертація
53
+
54
+
Для параметрів з такими типами значення конвертується без додаткових атрибутів:
55
+
56
+
| Тип параметра | Що передає клієнт | Конвертор |
57
+
| --- | --- | --- |
58
+
| `BackedEnum` | значення case (`"paid"`) | `BackedEnumConvertor` |
59
+
| pure enum | назву case | `EnumConvertor` |
60
+
| `DateTime`, `DateTimeImmutable`, `DateTimeInterface` | рядок дати | `DateTimeConverter` |
61
+
| `Symfony\Component\Uid\*`, `Ramsey\Uuid\*` | рядок UUID | `UuidConverter` |
62
+
| сутність Doctrine | ідентифікатор | `DoctrineEntityConverter` |
63
+
64
+
```php
65
+
enum OrderStatus: string
66
+
{
67
+
case NEW = 'new';
68
+
case PAID = 'paid';
69
+
}
70
+
71
+
/**
72
+
* @param OrderStatus[] $statuses
73
+
*/
74
+
public function find(OrderStatus $status, array $statuses = []): array
75
+
76
+
// {"method": "Order.status", "params": {"order": 42}} — Order завантажиться за id
77
+
public function status(Order $order): string
78
+
```
79
+
80
+
`DoctrineEntityConverter` реєструється лише тоді, коли ввімкнено DoctrineBundle.
81
+
82
+
У відповіді ці типи перетворюються назад на скаляри: enum → значення, дата → рядок (`Y-m-d H:i:s`), UUID → рядок, сутність → ідентифікатор (або `__toString()` для `Stringable`).
83
+
84
+
## `#[RPC\Param]`
85
+
86
+
Атрибут явно задає, які скалярні типи приймає параметр і яким конвертором перетворювати значення. Потрібен, коли тип не підтримується автоматично або треба інший конвертор.
87
+
88
+
```php
89
+
public function __construct(
90
+
int $type, // бітова маска Param::STRING | Param::INT | Param::FLOAT | Param::NULL
91
+
bool $collection = false, // значення — масив, конвертується кожен елемент
92
+
array $context = [], // наприклад, [Param::C_CONVERTOR => MyConvertor::class]
93
+
)
94
+
```
95
+
96
+
```php
97
+
use Ufo\RpcObject\RPC;
98
+
99
+
public function charge(
100
+
#[RPC\Param(RPC\Param::STRING, context: [RPC\Param::C_CONVERTOR => MoneyConvertor::class])]
101
+
Money $amount,
102
+
): bool
103
+
```
104
+
105
+
Готові маски: `Param::NUMBER`, `Param::NULLABLE_STRING`, `Param::NULLABLE_NUMBER`, `Param::MIXED`.
106
+
107
+
## Власний конвертор
108
+
109
+
Реалізуйте `Ufo\JsonRpcBundle\ParamConvertors\IParamConvertor`. З autoconfigure клас автоматично отримує тег `rpc.param_convertor`, і параметри підтримуваного типу конвертуються без атрибута.
110
+
111
+
```php
112
+
use Ufo\JsonRpcBundle\ParamConvertors\IParamConvertor;
113
+
use Ufo\RpcObject\RPC\Param;
114
+
115
+
final class MoneyConvertor implements IParamConvertor
116
+
{
117
+
public function toScalar(object $object, array $context = [], ?callable $callback = null): array|string|int|float|null
118
+
{
119
+
return $object->amount;
120
+
}
121
+
122
+
public function toObject(int|string|float|null $value, array $context = [], ?callable $callback = null): ?object
123
+
{
124
+
return new Money((int) $value);
125
+
}
126
+
127
+
public function supported(string $classFQCN): bool
128
+
{
129
+
return $classFQCN === Money::class;
130
+
}
131
+
132
+
public function getParamAttr(string $classFQCN): Param
133
+
{
134
+
return new Param(Param::INT, context: [Param::C_CONVERTOR => self::class]);
135
+
}
136
+
}
137
+
```
138
+
139
+
## Спеціальні параметри `$rpc`
140
+
141
+
Об'єкт `$rpc` у `params` не передається в метод, а керує виконанням запиту:
142
+
143
+
| Ключ | Призначення |
144
+
| --- | --- |
145
+
| `callback` | URL, на який надіслати результат — див. [Webhook](/docs/api/json-rpc-bundle/functionality/callback) |
146
+
| `timeout` | Таймаут виконання, секунди (за замовчуванням 10) |
147
+
| `rayId` | Ідентифікатор батьківського запиту для трасування |
148
+
| `ignoreCache` | `true` — обійти [кеш відповіді](/docs/api/json-rpc-bundle/add_rpc_service/cache) і записати його заново |
149
+
150
+
```json
151
+
{"jsonrpc": "2.0", "id": 1, "method": "Orders.get", "params": {"id": 10, "$rpc": {"ignoreCache": true}}}
152
+
```