comodojo/rpcserver documentation

This library provides a framework (and transport) independent XML and JSON(2.0) RPC client.

Main features are:

  • full XMLRPC and JSONRPC (2.0) protocols support, including multicall and batch requests
  • PSR-3 compliant logging
  • configurable content encoding
  • content encryption (if used in combination with comodojo/rpcserver)

Installation

First install composer, then:

composer require comodojo/rpcclient

Requirements

To work properly, comodojo/rpcclient requires PHP >=5.6.0.

Basic Usage

Following a quick and dirty example of lib basic usage.

Note

For more detailed informations, please see Using the client and Composing requests pages.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
 <?php

 use \Comodojo\RpcClient\RpcClient;
 use \Comodojo\RpcClient\RpcRequest;
 use \Exception;

 try {

     // create a RpcClient instance (default XML)
     $client = new RpcClient( "http://phpxmlrpc.sourceforge.net/server.php" );

     // create and inject a request
     $client->addRequest( RpcRequest::create("echo", ['Hello Comodojo!']) );

     // send the request
     $result = $client->send();

 } catch (Exception $e) {

     /* something did not work :( */
     throw $e;

 }

 echo $result;

Composing requests

Each RPC request, regardless of the protocol, should be composed as an instance of the class \Comodojo\RpcClient\RpcRequest.

Each request, once created, generate it’s unique id that will never be transmitted to the server but is used to discriminate requests in case of batches.

For example, to invoke the echo method on the server side that may accept a parameter:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
 <?php

 use \Comodojo\RpcClient\RpcRequest;

 $request = new RpcRequest;
 $request
     ->setMethod('echo')
     ->setParameters([
         "Hello world!"
     ]);

Or using the static RpcRequest::create constructor:

1
2
3
4
5
 <?php

 use \Comodojo\RpcClient\RpcRequest;

 $request = RpcRequest::create('echo', ["Hello world!"]);

Handling special types

When using XML-RPC protocol, base64, datetime and cdata parameters must me explicitly declared using the RpcRequest::setSpecialType method, in order to produce a well formatted xml output.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
 <?php

 use \Comodojo\RpcClient\RpcRequest;

 $request = new RpcRequest;

 // base64 of: "I checked it very thoroughly", said the computer,
 //  "and that quite definitely is the answer. I think the problem,
 //  to be quite honest with you, is that you've never actually
 //  known what the question is."
 $parameters = [
     "IkkgY2hlY2tlZCBpdCB2ZXJ5IHRob3JvdWdob".
     "HkiLCBzYWlkIHRoZSBjb21wdXRlciwgImFuZC".
     "B0aGF0IHF1aXRlIGRlZmluaXRlbHkgaXMgdGh".
     "lIGFuc3dlci4gSSB0aGluayB0aGUgcHJvYmxl".
     "bSwgdG8gYmUgcXVpdGUgaG9uZXN0IHdpdGgge".
     "W91LCBpcyB0aGF0IHlvdSd2ZSBuZXZlciBhY3".
     "R1YWxseSBrbm93biB3aGF0IHRoZSBxdWVzdGl".
     "vbiBpcy4i"
 ];

 $request
     ->setMethod('echo')
     ->setParameters($parameters)
     ->setSpecialType($parameters[0], "base64");

About request id

When using a JSON-RPC protocol, each request should have it’s own id, otherwise it is assumed to be a notification.

Note

Please see jsonrpc specs for more information about how request are structured and interpreted.

By default, this library will assign a random id to each request. The method RpcRequest::setId is availabe to override this behaviour:

  • if id is set to true, the lib will generate a random id (default behaviour);
  • if id is an integer or a string, it will be left intact;
  • if id is set to null, the request will be treated as a notification.

Using the client

Once a request is composed, the \Comodojo\RpcClient\RpcClient class can be used to send it to the server and retrieve the response. It will seamlessly format the message according to selected protocol, send it to the server, read and decode the response.

1
2
3
4
5
6
7
8
 <?php

 use \Comodojo\RpcClient\RpcClient;
 use \Comodojo\RpcClient\RpcRequest;

 $client = new RpcClient("http://phpxmlrpc.sourceforge.net/server.php");
 $client->addRequest( RpcRequest::create("echo", ['Hello Comodojo!']) );
 $result = $client->send();

Optionally, the client can be configured to use a PSR-3 compliant logger and/or a custom transport (second and third arguments, see below).

The autoclean switch

By default, the client will hold one or more requests until the RpcClient::send method is invoked and it cleans the request’s stack when a response is received.

This behaviour can be overridden using the RpcClient::setAutoclean method that will force the client to keep each request and reply it on next iteration.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
 <?php

 use \Comodojo\RpcClient\RpcClient;
 use \Comodojo\RpcClient\RpcRequest;

 $client = new RpcClient("http://phpxmlrpc.sourceforge.net/server.php");
 $client->setAutoclean(false);
 $client->addRequest( RpcRequest::create("echo", ['Hello Comodojo!']) );
 $result = $client->send();
 $client->addRequest( RpcRequest::create("echo", ['Hello Comodojo...2!']) );

 // client will send two requests to the server and result will consequently contain two responses.
 $result = $client->send();

Selecting RPC protocol

To select XMLRPC (default) or JSONRPC protocols:

1
2
3
4
5
6
7
8
 <?php

 use \Comodojo\RpcClient\RpcClient;

 $client = new RpcClient("http://phpxmlrpc.sourceforge.net/server.php");
 $client->setProtocol(RpcClient::JSONRPC);
 // or
 // $client->setProtocol(RpcClient::XMLRPC);

Change default encoding

By default, client will encode requests in utf-8. To select a different encoding:

1
2
3
4
5
6
 <?php

 use \Comodojo\RpcClient\RpcClient;

 $client = new RpcClient("http://phpxmlrpc.sourceforge.net/server.php");
 $client->setEncoding('ISO-8859-2');

Transport

The RpcClient comes with an embedded HTTP transport manager that makes use of comodojo/httprequest lightweight library.

If class is not inited with a custom transport, this one will be used.

To access transport instance, the RpcClient::getTransport method can be used before invoking RpcClient::send.

Custom transport classes should implement the \Comodojo\RpcClient\Interfaces\Transport. The SocketTransport of comodojo/daemon library is a good example to start with.

Encryption

When used in combination with comodojo/rpcserver, the RpcClient can be configured to seamlessly encrypt messages and decrypt reponses using a pre shared key.

To enable this feature, a key can be passed to RpcClient::getTransport method:

1
2
3
4
5
6
 <?php

 use \Comodojo\RpcClient\RpcClient;

 $client = new RpcClient("http://example.com/rpcserver");
 $client->setEncryption('this is my super secret key');