logo

JSON-RPC PHP

[en] [it]
Index

Example

This exercise makes both a server-side system and a client-side system to realize a complete JSON-RPC case-study.
The two sides, as you're going to see, are totally indipendent and they complement themselves for the pratice pourpose only.

Server

Suppose to have got an hosted class example [code] doing some operations in the local system.
The operations could be an informations request:

public function giveMeSomeData($param);

the supply of an information to be stored in the system:

public function changeYourState($state);

or a very important information storage in a database:

public function writeSomething($something);

moreover, there are some protected or private methods and some proprieties.

It's easy to conceive a localUsage example [code] of the objects of the example class:

require_once 'example.php';
$myExample = new example();

Suppose, also, that the same functionalities must be offered to some partners attending on the network, acting on different hosts.
A good way to aim the goal is JSON-RPC PHP. The RPC server could have the form:

<?php
require_once 'jsonRPCServer.php';
require 
'example.php';

$myExample = new example();
jsonRPCServer::handle($myExample)
    or print 
'no request';
?>

That's all.

Once called with a weel formed JSON-RPC request, via HTTP-POST, the server will offer the same public methods of the example class, accept the same parameters and returns the same values.
The JSON-RPC language is detailed in the specification.

Obviously, offering all public methods could be more than desired. It's possible that some operations are wanted unavailable to remote consumers, but restricted to the local users of the class.

To be simple, JSON-RPC PHP doesn't offer a direct solution to this problem. This problem, in fact, can be easly resolved by the service developer with simple and ordinary techniques.

Suppose, e.g., that the method:

public function writeSomething($something);

should be unavailable to the remote users. Simply, an extension restrictedExample [code] is required, overriding the writeSomething() in a dummy way as:

public function writeSomething($something) {
        throw new 
Exception('writeSomething method
                is not available for RPC'
);
    }

Once done, the writeSomething() method become unavailable from the network if the RPC has been builded via the new class.

So, the new server [code], has the form:

<?php
require_once 'jsonRPCServer.php';
require 
'example.php';
require 
'restrictedExample.php';

$myExample = new restrictedExample();
jsonRPCServer::handle($myExample)
    or print 
'no request';
?>

Folks wanting test their clients, both server and localUsage of this example are available and working.

Client

The client usage is very simple.

suppose to know the existence of a JSON-RPC service, to know its methods and their features.
To simplify the example, suppose that the server could be the server of the above paragraph. As you'll see, it's unnecessary that both client and server are builded via JSON-RPC PHP classes.

Once the service features are known, a client example [code] can be builded as follow:

require_once 'jsonRPCClient.php';
$myExample = new jsonRPCClient('http://localhost/server.php');

The objects of the jsonRPCClient class so builded have the same methods of the RPC service available.

That's all.

Folks wanting veerify the class behaviour, the client output is available and working.

Concurrent usage of the JSON-RPC PHP client and server

Concurrently using both classes gives an interesting example to explane the logic.

Observing the localUsage example (on the server side) of the example class and a client example on a remote host, it shows clearly that the resulting code is prefectly identical, except, obviously, the creation instruction.

The only difference could be that if on the server side the classe usage has been restricted (in the restrictedExample way), the modified or erased methods would not have the same effect.

localUsage [execute]

<?php
require_once 'example.php';
$myExample = new example();

// performs some basic operation
echo '<b>Attempt to perform basic operations</b><br />'."\n";
try {
    echo 
'Your name is <i>'.$myExample->giveMeSomeData('name').'</i><br />'."\n";
    
$myExample->changeYourState('I am using this function from the local environement');
    echo 
'Your status request has been accepted<br />'."\n";
} catch (
Exception $e) {
    echo 
nl2br($e->getMessage()).'<br />'."\n";
}

// performs some strategic operation, locally allowed
echo '<br /><b>Attempt to store strategic data</b><br />'."\n";
try {
    
$myExample->writeSomething('Strategic string!');
    echo 
'Strategic data succefully stored';
} catch (
Exception $e) {
    echo 
nl2br($e->getMessage());
}
?>

client [execute]

<?php
require_once 'jsonRPCClient.php';
$myExample = new jsonRPCClient('http://jsonrpcphp.org/server.php');

// performs some basic operation
echo '<b>Attempt to perform basic operations</b><br />'."\n";
try {
    echo 
'Your name is <i>'.$myExample->giveMeSomeData('name').'</i><br />'."\n";
    
$myExample->changeYourState('I am using this function from the network');
    echo 
'Your status request has been accepted<br />'."\n";
} catch (
Exception $e) {
    echo 
nl2br($e->getMessage()).'<br />'."\n";
}

// performs some strategic operation, locally allowed
echo '<br /><b>Attempt to store strategic data</b><br />'."\n";
try {
    
$myExample->writeSomething('Strategic string!');
    echo 
'Strategic data succefully stored';
} catch (
Exception $e) {
    echo 
nl2br($e->getMessage());
}
?>

This comparison explain definitively the JSON-RPC PHP spirit.

disclaimer - copyright
JSON-RPC PHP
A free and easy way to RPC

Valid XHTML 1.1 Valid CSS 2.1     PHP Powered Apache Powered
18 December 2014, 02:33 GMT