1. Встановлення

Остання зміна 2024/07/11 09:57 автором Ashterix

Зміст

Крок 0: Налаштування composer.json
Крок 1: Встановлення
Крок 2: Реєстрація пакету
Крок 3: Додавання параметрів
Крок 4: Реєстрація маршрутів
Крок 5: Profit
Що далі?

Крок 0: Налаштування composer.json

Для того, щоб при додаванні пакету, ваш Symfony Flex автоматично зробив всі необхідні налаштування, потрібно внести наступні зміни в ваш composer.json

composer.json

1
2
3
4
5
6
7
8
9
10

{
   "extra" : {
       "symfony": {
           "endpoint": [
               "https://api.github.com/repos/ufo-tech/recipes/contents/index.json?ref=main",
               "flex://defaults"
            ]
        }
    },
}

Детально про Symfony Flex в документації Symfony

Крок 1: Встановлення

В консолі в теці проєкту виконайте цю команду, щоб завантажити останню версію цього пакету:

composer require ufo-tech/json-rpc-bundle

Ця команда актуальна якщо ви встановили Composer глобально, як описано в документації Composer.

Крок 2: Реєстрація пакету

Переконайтесь, що пакет автоматично зареєструвався в файлі config/bundles.php вашого проєкту:

config/bundles.php

1
2
3
4
5
6
7

<?php

return [
   // ...
   Ufo\JsonRpcBundle\UfoJsonRpcBundle::class => ['all' => true],
   // ...
];

Крок 3: Додавання параметрів

Якщо ви виконали «Крок 0», це налаштовано автоматично і ви можете пропустити цей крок.

В разі ручного налаштування бандлу, додайте до папки config/packages файл ufo_json_rpc.yaml із таким вмістом:

config/packages/ufo_json_rpc.yaml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

ufo_json_rpc:
   security:
       protected_methods: ['POST']               # Protection of GET and POST requests
       token_key_in_header: 'Ufo-RPC-Token'      # Name of the key in the header
       clients_tokens:
            - 'ClientTokenExample'                # Hardcoded token example. Importantly!!! Replace or delete it!
            - '%env(resolve:UFO_API_TOKEN)%'      # Token example from .env.local

   # Configuration for API documentation
   docs:
       # Optional response details
       response:
           key_for_methods: services       # Key used to map services for API methods
           # Information about validations
           validations:
               json_schema:     false      # Indicates if JSON-schema is used for method validation
               symfony_asserts: false      # Indicates if an array of Symfony validation constraints is used

Детальний огляд параметрів налаштування доступний в розділі Налаштування бандлу

Крок 4: Реєстрація маршрутів

Якщо ви виконали «Крок 0», це налаштовано автоматично і ви можете пропустити цей крок.

В разі ручного налаштування бандлу, додайте до папки config/routes файл ufo_json_rpc.yaml із таким вмістом:

config/routes/ufo_json_rpc.yaml

1
2
3
4

ufo_json_rpc:
   resource: ../../vendor/ufo-tech/json-rpc-bundle/config/router.yaml
   prefix: /api
   trailing_slash_on_root: false

Якщо лишити налаштування як є, то RPC API буде доступне по шляху /api наприклад https://example.com/api
Якщо вам потрібно змінити шлях, змініть налаштування маршруту таким чином:

config/routes/ufo_json_rpc.yaml

1
2
3
4

ufo_json_rpc_bundle:
   resource: ../../vendor/ufo-tech/json-rpc-bundle/config/router.yaml
   prefix: /my_custom_api_route   #вкажіть тут альтернативний шлях
   trailing_slash_on_root: false

Тепер API буде доступне по шляху https://example.com/my_custom_api_route

Крок 5: Profit

Вітаю!!! Ваш RPC сервер готовий до роботи!!!

Що далі?

А воно точно працює? (с)

GET запит на точку входу поверне документацію по наявним методам і параметрам, які вони приймають.

Формат документації може змінюватися в залежності від ваших налаштувань. Див. Налаштування бандлу

GET: /api

{
   "envelope": "JSON-RPC-2.0/UFO-RPC-6",
   "contentType": "application/json",
   "description": "",
   "transport": {
       "sync": {
           "scheme": "https",
           "host": "example.com",
           "path": "/api",
           "method": "POST"
        }
    },
   "methods": {
      "ping": {
          "name": "ping",
           "description": "",
           "parameters": [],
           "returns": "string",
           "responseFormat": "string"
        }
    }
}

Метод ping встановлений одразу, ви можете одразу виконати POST запит, щоб переконатися, що сервер працює.

POST: /api

Request:

{
"id": "some_request_id",
"method": "ping"
}

Response:

{
"id": "some_request_id",
"result": "PONG"
}