README

Symfony JSON-RPC HTTP Server to convert an HTTP json-rpc request into HTTP json-rpc response.

Symfony bundle for yoanm/jsonrpc-server-sdk

See yoanm/symfony-jsonrpc-params-validator for params validation.

See yoanm/symfony-jsonrpc-http-server-doc for documentation generation.

Versions

• Symfony v3/4 - PHP >=7.1 : ^2.0

  ⚠️⚠️ v2.1.0 and v2.1.1 were badly taggued, used v3.0.0 instead ! ⚠️⚠️

• Symfony v4/5 - PHP >=7.2 : ~3.0.0

• Symfony v4/5 - PHP >=7.3 : ^3.1

• Symfony v4.4/5.4 - PHP ^8.0 : ^3.2

• Symfony v4.4/5.4/6.x - PHP ^8.0 : ^3.3

• Symfony v5.4/6.4/7.x - PHP ^8.0 : ^4.0

How to use

Once configured, your project is ready to handle HTTP POST request on /json-rpc endpoint.

See below how to configure it.

Configuration

Bundle requires only one thing :

• JSON-RPC Methods which are compatible with yoanm/jsonrpc-server-sdk

It comes with built-in method resolver which use a service locator. Using a service locator allow to load (and so instanciate dependencies, dependencies of dependencies, etc) method only when required (usually only one method is required by request, except for batch requests which will load one or more methods).

Behat demo app configuration folders can be used as examples.

• Add the bundles in your config/bundles.php file:

  // config/bundles.php
  return [
      ...
      Symfony\Bundle\FrameworkBundle\FrameworkBundle::class => ['all' => true],
      Yoanm\SymfonyJsonRpcHttpServer\JsonRpcHttpServerBundle::class => ['all' => true],
      ...
  ];

• Add the following in your routing configuration :

  # config/routes.yaml
  json-rpc-endpoint:
    resource: '@JsonRpcHttpServerBundle/Resources/config/routing/endpoint.xml'

• Add the following in your configuration :

  # config/config.yaml
  framework:
    secret: '%env(APP_SECRET)%'
  
  json_rpc_http_server: ~
  # Or the following in case you want to customize endpoint path
  #json_rpc_http_server:
  #  endpoint: '/my-custom-endpoint' # Default to '/json-rpc'

JSON-RPC Method mapping

In order to inject yours JSON-RPC method into the server add the tag json_rpc_http_server.jsonrpc_method and the key/value method like following example :

services:
   method-a.service-id:
      class: Method\A\Class
      tags:
       - { name: 'json_rpc_http_server.jsonrpc_method', method: 'method-a' }
       - { name: 'json_rpc_http_server.jsonrpc_method', method: 'method-a-alias' }

Methods mapping aware

In case you want to be aware of which methods are registered inside the JSON-RPC server, you can use the json_rpc_http_server.method_aware. Your class must implements JsonRpcMethodAwareInterface.

use Yoanm\JsonRpcServer\Domain\JsonRpcMethodAwareInterface;
use Yoanm\JsonRpcServer\Domain\JsonRpcMethodInterface;

class MappingCollector implements JsonRpcMethodAwareInterface
{
  /** @var JsonRpcMethodInterface[] */
  private $mappingList = [];

  public function addJsonRpcMethod(string $methodName, JsonRpcMethodInterface $method): void
  {
    $this->mappingList[$methodName] = $method;
  }

  /**
   * @return JsonRpcMethodInterface[]
   */
  public function getMappingList() : array
  {
    return $this->mappingList;
  }
}

mapping_aware_service:
  class: App\Collector\MappingCollector
  tags: ['json_rpc_http_server.method_aware']

Debug mode

You can setup 'debug' mode for the JSON-RPC server, which allows display of verbose error information within the response JSON body. This information contains actual exception class name, code, message and stack trace.

Note: you should never enable 'debug' mode in 'production' environment, since it will expose vital internal information to the API consumer.

Configuration example:

# file 'config/packages/json_rpc.yaml'
json_rpc_http_server:
  endpoint: '/json-rpc'
  debug:
    enabled: false
    max_trace_size: 10
    show_trace_arguments: true
    simplify_trace_arguments: true

when@dev:
  json_rpc_http_server:
    debug:
      enabled: true

when@test:
  json_rpc_http_server:
    debug:
      enabled: true

Contributing

See contributing note