Installing JsonRpcBundle

← Installing JsonRpcBundle

Ashterix

docs: rewrite JsonRpcBundle docs, add SDK docs, move them under docs/api

en/docs/api/json-rpc-bundle/installation.md new file +153 −0

Installing JsonRpcBundle

Requirements for version 10.x: PHP >= 8.4, Symfony ^7.2 or ^8.0, the ext-dom and ext-sysvsem extensions.

Step 0: composer.json configuration

For Symfony Flex to apply all the configuration automatically when the package is installed, add the UFO-Tech recipes repository to your composer.json:

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

For details on private Symfony Flex recipes, see the Symfony documentation.

Step 1: Installation

In the project directory, run the command to download the latest version of the package:

composer require ufo-tech/json-rpc-bundle

Step 2: Registering the package

Make sure the package is registered in config/bundles.php:

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

Step 3: Configuration

If you completed "Step 0", the file was created automatically and you can skip this step.

Add the config/packages/ufo_json_rpc.yaml file with a minimal configuration:

# config/packages/ufo_json_rpc.yaml
ufo_json_rpc:
    security:
        protected_api: true               # check the token for RPC requests
        protected_doc: false              # documentation is open
        token_name: 'Ufo-RPC-Token'       # name of the header with the token
        clients_tokens:
            - '%env(resolve:UFO_API_TOKEN)%'

    docs:
        project_name: 'My Project'

and the token in .env.local:

UFO_API_TOKEN=change-me

All parameters are described in the Bundle configuration section.

Step 4: Registering routes

If you completed "Step 0", the file was created automatically and you can skip this step.

Add the config/routes/ufo_json_rpc.yaml file:

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

The API will be available at https://example.com/rpc. To change the path, change prefix.

Before version 10, the installation recipe used the /api prefix. Existing route files are not changed on upgrade, so old projects keep working at the previous address.

One application can have several entry points with different sets of methods; see API groups.

Step 5: Profit

Congratulations!!!

Your RPC server is ready to go!!!

Verification

Does it really work? (c)

Request What it returns
GET /rpc OpenRPC document with all methods
GET /rpc?info Only the document header (info, servers), without methods
GET /rpc/postman Postman collection
POST /rpc Executes a JSON-RPC request

The ping method is installed right away, so you can send a POST request:

Request:

curl -X POST https://example.com/rpc \
  -H 'Content-Type: application/json' \
  -H 'Ufo-RPC-Token: change-me' \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "ping"}'

Response:

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": "PONG"
}

The same from the console:

php bin/console ufo:rpc:process '{"jsonrpc": "2.0", "id": 1, "method": "ping"}' --ufo-rpc-token=change-me

What's next?