docs: rewrite JsonRpcBundle docs, add SDK docs, move them under docs/api
uk/docs/api/sdk/client/extending.md
new file +70
−0
1
+
# Розширення SDK
2
+
3
+
## Джерело документації: `IDocReader`
4
+
5
+
```php
6
+
namespace Ufo\RpcSdk\Maker\DocReader\Interfaces;
7
+
8
+
interface IDocReader
9
+
{
10
+
public function getApiDocumentation(): array; // декодований документ OpenRPC
11
+
}
12
+
```
13
+
14
+
Вбудовані: `HttpReader(string $apiUrl, array $headers = [])` — за URL, зокрема із заголовком токена для захищеної документації; `FileReader(string $docFilePath)` — з локального JSON. Власний читач (наприклад, документ з репозиторію чи об'єднання кількох) передається в `ConfigsHolder`.
15
+
16
+
## Генератори: `IMaker`
17
+
18
+
```php
19
+
namespace Ufo\RpcSdk\Maker\Interfaces;
20
+
21
+
interface IMaker
22
+
{
23
+
public function make(?callable $callbackOutput = null): void;
24
+
}
25
+
```
26
+
27
+
`Maker(ConfigsHolder $configs, Generator $generator, IMaker[] $makers)` запускає генератори по черзі; `$callbackOutput` отримує кожне згенероване визначення (`IClassLikeDefinition`) — так виводиться перелік класів у консоль. Вбудовані: `SdkEnumMaker`, `SdkDtoMaker`, `SdkProcedureMaker`, `SdkConfigMaker`.
28
+
29
+
## Власні шаблони
30
+
31
+
Окремої опції для шаблонів немає. Успадкуйте потрібний генератор і перевизначте властивість `$template`:
32
+
33
+
```php
34
+
final class MyProcedureMaker extends SdkProcedureMaker
35
+
{
36
+
protected string $template = __DIR__.'/templates/procedure.php';
37
+
}
38
+
```
39
+
40
+
Вбудовані шаблони лежать у `templates/` пакета (`procedure`, `sync_method`, `async_method`, `dto`, `enum`, `namespace`, `docs`). Попри розширення `.php.twig`, це PHP-шаблони MakerBundle, не Twig.
41
+
42
+
## Обробники відповіді: `IResponseHandler`
43
+
44
+
```php
45
+
namespace Ufo\RpcSdk\Procedures\ResponseTransformer\Interfaces;
46
+
47
+
interface IResponseHandler // тег ufo.sdk_response_handler, const int PRIORITY = 0
48
+
{
49
+
public function canHandle(array $schema): bool;
50
+
public function handle(array $schema, mixed $result, callable $transform, SdkResponseCreator $creator): mixed;
51
+
}
52
+
```
53
+
54
+
Обробник отримує JSON Schema очікуваного результату (з `@return` методу). Перший, чий `canHandle()` повернув `true`, перетворює значення; `$transform` рекурсивно обробляє вкладені значення. Передаються аргументом `$handlers` конструктора процедури; **непорожній список повністю замінює стандартні**, тож додавайте й вбудовані (`EnumResponseHandler`, `UnionResponseHandler`, `CollectionResponseHandler`, `DtoResponseHandler`). SDK Bundle збирає всі сервіси з тегом і впорядковує за `PRIORITY`.
55
+
56
+
## Спеціальні параметри: `IRpcSpecialParamHandler`
57
+
58
+
Синхронні класи приймають власну реалізацію `Ufo\RpcObject\IRpcSpecialParamHandler` (аргумент `$rpcSpecialParams`) — наприклад, щоб автоматично додавати `rayId` з контексту трасування. За замовчуванням — `Ufo\RpcSdk\Procedures\RpcSpecialParamHandler`. Асинхронні класи власного обробника не приймають.
59
+
60
+
## Асинхронні транспорти
61
+
62
+
Див. [Асинхронні виклики](/docs/api/sdk/client/async): `AsyncTransportResolverInterface` / `AbstractAsyncTransportResolver` з пакета `ufo-tech/component-transport-contracts`.
63
+
64
+
## Атрибути
65
+
66
+
| Атрибут | Де | Призначення |
67
+
| --- | --- | --- |
68
+
| `#[ApiMethod('User.get')]` | метод | Назва RPC-методу |
69
+
| `#[ApiUrl($url, $method = 'POST')]` | клас | Явна адреса сервера замість `sdk_config.yaml` (генератор його не створює — див. [Актуальні помилки](/docs/api/sdk/client/known_issues/open)) |
70
+
| `#[AsyncTransport($dsn)]` | — | Допоміжний клас плейсхолдера секрету |