datto / php-json-rpc

Fully unit-tested JSON-RPC 2.0 for PHP

JSON-RPC for PHP

Overview

This package allows you to create and evaluate JSON-RPC messages, using your own PHP code to evaluate the requests.

This package allows you to create and evaluate any JSON-RPC message. It implements the JSON-RPC specifications, but does not provide a transport layer—which you'll also need if you want to send or receive messages over a distance! One of the beautiful features of JSON-RPC is that you can use any transport layer to carry your messages: This package gives you that option.

If you're looking for an end-to-end solution, with the transport layer included, then you should use one of these alternative packages instead:

• To send messages over HTTP(S), use the php-json-rpc-http package.
• To send messages over SSH, use the php-json-rpc-ssh package.

Features

• Correct: fully compliant with the JSON-RPC 2.0 specifications (100% unit-test coverage)
• Flexible: you can use your own code to evaluate the JSON-RPC method strings
• Minimalistic: extremely lightweight
• Ready to use, with working examples

Examples

Client

$client = new Client();

$client->query(1, 'add', array(1, 2));

$message = $client->encode();

// message: {"jsonrpc":"2.0","method":"add","params":[1,2],"id":1}

Server

$api = new Api();

$server = new Server($api);

$reply = $server->reply($message);

// reply: {"jsonrpc":"2.0","result":3,"id":1}

See the examples folder for full working examples.

Requirements

• PHP >= 7.0

License

This package is released under an open-source license: LGPL-3.0

Installation

If you're using Composer, you can include this library (datto/json-rpc) like this:

composer require "datto/json-rpc"

Getting started

1. Try the examples. You can run the examples from the project directory like this:

   php examples/client.php
   php examples/server.php
   

2. Take a look at the code "examples/src"—then replace it with your own!

Unit tests

You can run the suite of unit tests from the project directory like this:

./vendor/bin/phpunit

Changelog

See what has changed: Changelog

Author

Spencer Mortensen

php-json-rpc's Issues

ErrorException "Invalid JSON-RPC 2.0 response" thrown when decoding message with error object

I might be incorrect, but it seems that when decoding response from JSON RPC server, and response contains error object, parameter result is requested where as per specification it is not required:

And so decode fails and throws an errorException.

Proper error checking instead of @

Server.php/147:

        $version = @$request['jsonrpc'];
        if (@$version !== self::VERSION) {
        $method = @$request['method'];

Because on most dev servers it results in the following:

SCREAM: Error suppression ignored for
Notice: Undefined index: jsonrpc in /var/www/foo/vendor/datto/json-rpc/src/Server.php on line 147

Support for passing additional arguments to evaluators

I'm writing a PR for a feature that allows you to pass some additional arguments to reply(). The goal of this feature is to allow passing context to the RPC method such as (in my case) websocket caller information.

Use-case: Lets say I'm building a chat app with WebSocket and I'm using JSON-RPC messages as the protocol between the client and server. If the client calls sendMessage with some arguments like ["this is a message"], the ChatRoom\sendMessage function the server side needs to know how to relay the message back to the other clients. In this case, if all method calls contained a $clientContext, the ChatRoom class can keep state of who is in the room and what their $clientContext is. This would allow the sendMessage method to iterate over a list of clients and send messages to them as part of its business logic.

API change: This change would add a new optional parameter to reply such as $server->reply($clientMessage, array($clientContext)) and this new list of arguments would be appended to the arguments passed by the client already.

I want to gather some feedback on this idea before I fully lock down the code and submit the PR, what do you think?

Why ArgumentException can't receive data?

I want to pass additional information about validation error, but builtin ArgumentException don't receive any arguments in constructor. Why so?

Installation problem

composer require "datto/json-rpc" "~5.0"

I used the examples in the vendor folder which were installed by this command.

It's not working at all.

I spent few hours and tried below.
git clone https://github.com/datto/php-json-rpc.git
cd php-json-rpc-http
composer install

And used the commands in this document(https://github.com/datto/php-json-rpc-http/tree/master/examples/authenticated#run-the-examples)

Then it works.

Why don't you edit your installation part?

---

I have a question.

// Construct a client that can query your remote server over HTTP(S):
$client = new Client($url, $username, $password);

// Add the numbers "1" and "2":
$client->query(1, 'add', array(1, 2));

What means 1 in the first argument?

I'm trying to another server. but I don't know what it is.

Implementation::isValidCode($code) bug

php-json-rpc/src/Exception/Implementation.php

Line 92 in 597e946

return is_int($code) && (-32000 <= $code) && ($code <= -32099);

return is_int($code) && (-32000 <= $code) && ($code <= -32099);
should be changed to
return is_int($code) && (-32099 <= $code) && ($code <= -32000);
because the original condition is never true

Error code validation in `Evaluation` is reversed

On Line 47 in src/Exception/Evaluation.php, the method has its comparators flipped - when checking to see if -32768 <= $code <= -32000 like the spec says, the method actually returns false if the code is valid.

Support php8

Support php8?

Server reply option to not json encode result

Hi, I have a use case where I need to get the output as PHP value, means not encoded as json. Currently in the reply method of the server the output is always encoded as json see (https://github.com/datto/php-json-rpc/blob/master/src/Server.php#L70). What do you think about adding a new argument i.e. $encode = true which determines whether we encode the output or not? If you like I could create an PR for this.

Support custom json_encode options?

This lines:
https://github.com/datto/php-json-rpc/blob/master/src/Server.php#L74
https://github.com/datto/php-json-rpc/blob/master/src/Client.php#L110
shows me that I am not able to pass my custom json encoding options, like JSON_UNESCAPED_UNICODE.

But it is commonly used for non-english texts, at least for debugging purposes.

Implement batch client

The client implementation here is pretty simplistic, it just generates the request JSON but doesn't really do anything with the response JSON.

Would be nice if it was enhanced to also handle batch responses and validate them etc.

I may write a PR later if I find that I actually need it.