docs: rewrite JsonRpcBundle docs, add SDK docs, move them under docs/api
uk/docs/api/json-rpc-bundle/functionality/events/error.md
новий файл +113
−0
1
+
# rpc.error
2
+
3
+
::::::block class="floatinginfobox floatinginfobox--fit"
4
+
:::::columns border zebra
5
+
::::row
6
+
:::col width="40%"
7
+
**Назва події**
8
+
:::
9
+
:::col
10
+
`rpc.error`
11
+
:::
12
+
::::
13
+
::::row
14
+
:::col width="40%"
15
+
**Константа**
16
+
:::
17
+
:::col
18
+
`RpcEvent::ERROR`
19
+
:::
20
+
::::
21
+
::::row
22
+
:::col width="40%"
23
+
**Клас**
24
+
:::
25
+
:::col
26
+
`RpcErrorEvent`
27
+
:::
28
+
::::
29
+
::::row
30
+
:::col width="40%"
31
+
**Властивості**
32
+
:::
33
+
:::col
34
+
`RpcRequest $rpcRequest`, `Throwable $exception`, `RpcError $rpcError`
35
+
:::
36
+
::::
37
+
:::::
38
+
::::::
39
+
40
+
Помилка під час виконання запиту. `$rpcError` — об'єкт помилки, з якого буде сформовано відповідь; його можна замінити.
41
+
42
+
## Коли генерується
43
+
44
+
* Помилки валідації параметрів і `#[RPC\Assertions]`.
45
+
* Помилки конвертації параметрів (DTO).
46
+
* Виняток або `TypeError` з методу.
47
+
* Запит, позначений помилкою на попередніх етапах (`setError()`).
48
+
* У консолі, inline-batch і через `RpcExecutor` — також для будь-якого іншого винятку обробки.
49
+
50
+
:::warning subtitle="Нестиковка"
51
+
В одиночному HTTP-запиті частина помилок (недійсний JSON, токен, невідомий метод, версія `jsonrpc`, batch) не проходить через `rpc.error` і не логується бандлом. Деталі — в [Актуальних помилках](/docs/api/json-rpc-bundle/developers/known_issues/open).
52
+
:::
53
+
54
+
## Вбудовані лістенери
55
+
56
+
| Пріоритет | Лістенер | Що робить |
57
+
| --- | --- | --- |
58
+
| 1000 | `RpcErrorListener` | Для `ConstraintsImposedException` додає перелік порушень у `data` |
59
+
| 0 | `LoggerListener` | Пише помилку в лог (метод, параметри, дані) |
60
+
| -1000 | `RpcServerListener::onRpcError` | Формує відповідь з помилкою з `$event->rpcError` (`rpc.pre_response`) і зупиняє поширення |
61
+
62
+
## Що можна змінити
63
+
64
+
`$event->rpcError` — підтримуваний спосіб змінити помилку, яку отримає клієнт:
65
+
66
+
```php
67
+
$event->rpcError = new RpcError($code, $message, $data);
68
+
```
69
+
70
+
* Пріоритет між 1000 і 0 — ваша версія піде і в лог, і клієнту; між 0 і -1000 — лог побачить оригінал.
71
+
* `$rpcError` створюється з `$exception` у конструкторі; присвоєння нового `$exception` його не перераховує.
72
+
* Лістенери нижче -1000 не викликаються. Не зупиняйте поширення вище -1000 — відповідь з помилкою не буде сформовано.
73
+
74
+
## Приклади використання
75
+
76
+
### Приховати внутрішні подробиці
77
+
78
+
```php
79
+
#[AsEventListener(RpcEvent::ERROR, priority: 500)]
80
+
final class HideInternalErrorsListener
81
+
{
82
+
public function __construct(#[Autowire('%kernel.environment%')] private string $env) {}
83
+
84
+
public function __invoke(RpcErrorEvent $event): void
85
+
{
86
+
if ($this->env === 'prod' && $event->exception instanceof RpcRuntimeException) {
87
+
$event->rpcError = new RpcError(-32500, 'Internal server error', []);
88
+
}
89
+
}
90
+
}
91
+
```
92
+
93
+
### Відправка в систему моніторингу
94
+
95
+
```php
96
+
#[AsEventListener(RpcEvent::ERROR, priority: 100)]
97
+
final class SentryListener
98
+
{
99
+
public function __invoke(RpcErrorEvent $event): void
100
+
{
101
+
\Sentry\withScope(function (\Sentry\State\Scope $scope) use ($event): void {
102
+
$scope->setTag('rpc.method', $event->rpcRequest->getMethod());
103
+
\Sentry\captureException($event->exception);
104
+
});
105
+
}
106
+
}
107
+
```
108
+
109
+
### Інші ідеї
110
+
111
+
* перетворення доменних винятків застосунку на власні коди помилок;
112
+
* лічильник помилок за методом і кодом;
113
+
* додавання `request_id` у `data` помилки для підтримки.