Client usage

Contents

• Basic usage
• Batch requests
• Custom request headers
• Custom transport class

Basic usage

mszewcz/php-json-rpc works with PSR-4 autoloader. If you're using a composer just include its autoloader and use use statements for cleaner access to library classes:

require_once 'vendor/autoload.php';

use \MS\Json\Rpc\Client;
use \MS\Json\Rpc\Client\Notification;
use \MS\Json\Rpc\Client\Request;
// if you wish to make requests with cURL transport class instead of stream context:
use \MS\Json\Rpc\Client\Transport\CurlTransport;

To make a simple request/notification you have to:

• create new instace of Client class and pass $serverUrl as a first param
• add new Request/Notification object to queue
• send request & get response
• catch any exceptions that could be thrown by Client or Transport class

$serverUrl = 'http://your.server/system/';

// In case you want to add Authorization header to each request with 
// JSON web token value, please define the JWT cookie name:
define('JSON_WEB_TOKEN_COOKIE', 'your_json_web_token_cookie_name');

try {
    $client = new Client($serverUrl);
    $client->add(new Request(1, 'getConfiguration'));
    $client->send();
    $response = $client->getResponse();

    if ($response!==null) {
        // just to have pretty output
        echo json_encode($response, JSON_PRETTY_PRINT);
    }
} catch (\Exception $e) {
    echo $e->getMessage();
}

Batch requests

If you want to send more than one request in a time (batch request) just add another Request/Notification objects to queue:

...
$client->add(new Request(1, 'sum', [1, 3]));
$client->add(new Request(2, 'multiply', [2, 4]));
$client->add(new Notification('hello'));
$client->add(new Request(3, 'divide', [10, 5]));
$client->send();
...

Notice: Only one namespace can be used for batch requests at a time (as namespace is a part of $serverUrl passed to Client class), so you cannot do the following batch:

• request1 to namespace1
• request2 to namespace1
• request3 to namespace2
• request4 to namespace1

Custom headers

By default Client sends a request with following HTTP headers:

Content-Type: application/json; charset=utf-8
Accept: application/json
Content-Length: ...

If cookie for JSON web token is found following header will also be send:

Authorization: Baerer <json_web_cookie_value>

otherwise client looks for cookie named XSRF-TOKEN and if found sends following headers:

X-XSRF-TOKEN: <xsrf_token_cookie_value>

Notice: JSON WEB TOKEN cookie name has to be defined by user prior to Client class initialization (see Basic usage).

Notice 2: The XSRF is rather meant to be sent by JavaScript apps, which shouldn't have access to JSON web cookie (httpOnly: true), but Client will send it anyway if found and no JSON web token cookie is present.

If you want to add custom header(s) just call addHeaders() method before sending request. You can pass string as well as array of strings in case you want to add more than one header:

// Adding one custom header
$client->addHeaders(['name' => 'CustomHeader1', 'value' => 'value1']);

// Adding more than one custom header (better way)
$client->addHeaders([
    ['name' => 'CustomHeader1', 'value' => 'value1'], 
    ['name' => 'CustomHeader2', 'value' => 'value2']
]);

// Adding more than one custom header (worse way)
$client->addHeaders(['name' => 'CustomHeader1', 'value' => 'value1']);
$client->addHeaders(['name' => 'CustomHeader2', 'value' => 'value2']);

If you want to change default headers you just set them again and they will be overwritten:

$client->addHeaders(['name' => 'Content-Type', 'value' => 'application/json']);

If you want to remove header(s):

// remove one header:
$client->removeHeaders('Content-Type');
// or:
$client->removeHeaders(['Content-Type']);

// remove more headers:
$client->removeHeaders(['Content-Type', 'Accept']);

If you want to clear all headers:

$client->clearHeaders();

Notice: Content-Length header is added in $client->send(); method just before making a request and you cannot clear this one.

Custom transport class

By default Client sends requests using stream_context_create() and file_get_contents() functions. If you want to make requests using cURL library instead just pass CurlTransport class as a second argument to client:

$client = new Client($serverUrl, new CurlTransport());

You can also create your own transport class and pass it to Client. Your class has to extend AbstractTransport class and therefore needs to implement send() method:

use \MS\Json\Rpc\Client\Exceptions\ConnectionException;
use \MS\Json\Rpc\Client\Transport\AbstractTransport;

class CustomTransport extends AbstractTransport
{
    /**
     * Sends request to server
     *
     * @throws ConnectionException
     * @return void
     */
    public function send(): void
    {
        // Your method implementation. You can get server URL, headers and data from 
        // the following methods:
        // $this->getUrl()- server URL
        // $this->getHeaders() - array of string headers
        // $this->getData() - json encoded data from Client

        // the good practice is to throw ConnectionException in case of any problems 
        // when connecting to server:
        if ($responseFromServer === false) { // or any other equivalent condition
            throw new ConnectionException($this->getUrl());
        }
        
        // At the end you need to set response:
        $this->setResponse($responseFromServer);
    }
}