1. Installation

Last modified by Ashterix on 2024/07/11 09:57

Contents

Step 0: Setting up composer.json
Step 1: Installation
Step 2: Registering the Package
Step 3: Adding Parameters
Step 4: Route Registration
Step 5: Profit
What Next?

Step 0: Setting up composer.json

To ensure that adding a package automatically configures your Symfony Flex, make the following changes to your 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"
            ]
        }
    },
}

Learn more about Symfony Flex in the Symfony documentation

Step 1: Installation

In your project directory's console, execute this command to download the latest version of this package:

composer require ufo-tech/json-rpc-bundle

This command is relevant if you have installed Composer globally, as described in the Composer documentation

Step 2: Registering the Package

Ensure that the package is automatically registered in your project's config/bundles.php file:

config/bundles.php

1
2
3
4
5
6
7
8
9

<?php

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

Step 3: Adding Parameters

If you completed “Step 0,” this is configured automatically, and you can skip this step.

For manual configuration of the bundle, add to the config/packages directory a file named ufo_json_rpc.yaml with the following content:

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

A detailed overview of configuration parameters is available in the Bundle Settings section

Step 4: Route Registration

If you completed “Step 0,” this is configured automatically, and you can skip this step.

For manual configuration of the bundle, add to the config/routes directory a file named ufo_json_rpc.yaml with the following content:

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

If left as is, the RPC API will be accessible at /api e.g. https://example.com/api
If you need to change the path, modify the route configuration as follows:

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   # specify an alternative path here
   trailing_slash_on_root: false

Now the API will be accessible at https://example.com/my_custom_api_route

Step 5: Profit

Congratulations!!! Your RPC server is ready to operate!!!

What Next?

Does it really work? (c)

A GET request at the entry point will return documentation on the available methods and the parameters they accept.

The format of the documentation may vary depending on your settings. See Bundle Settings

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"
        }
    }
}

The ping method is set up immediately, you can execute a POST request right away to ensure that the server is operating.

POST: /api

Request:

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

Response:

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