bit3 / remote-objects
Remote object method invokation framework
Requires (Dev)
- monolog/monolog: ~1.3
- phpseclib/phpseclib: *
- phpunit/phpunit: ~3
Suggests
- monolog/monolog: Required for logging.
- phpseclib/phpseclib: Required for encrypted transport.
This package is not auto-updated.
Last update: 2022-02-01 12:23:25 UTC
README
Com'on, not another method invocation framework? Aren't there enough XML-RPC, JSON-RPC and similar implementations out there? Yes, there are, but they are not flexible enough and most of them do not provide any security features like encryption.
The benefit of RemoteObjects is to provide a remote method invocation framework, that is secure (allow encryption), flexible (allow different transports like unix socket) and interoperable (support JSON-RPC 2.0 by default, but can also support XML-RPC or other protocols). Every component is exchangeable, if you like, you are also able to invoke a method via SMS as transport layer, or just use your own protocol instead of JSON-RPC. Everything is possible!
Or in other words: This framework combines the pros of all the others ;-)
How it works
user -> Client::invoke($method, $params)
\
\--> Encoder::encodeMethod($method, $params)
/
$request <-/
\
\--> Transport\Client::request($request)
|
|
HTTP or something else :-)
|
V
Transport\Server::receive()
/
$request <-/
\
\--> Encoder::decodeMethod($request)
/
[$method, $params] <-/
\
\--> Server::invokeArgs($method, $params)
\
\--> $target->$method($params..)
/
$result <--/
\
\--> Encoder::encodeResult($result)
/
$response <--/
\
\--> Transport\Server:respond($response)
|
|
All the way back
|
V
Transport\Client::request(...)
/
$response <--/
\
\--> Encoder::decodeResult($response)
/
$result <--/
/
user <--/
Usage example
A usage example using JSON-RPC 2.0 as protocol and a unix socket as transport layer.
server.php
class RemoteObject { public function reply($name) { return 'Hello ' . $name; } } $transport = new RemoteObjects\Transport\UnixSocketServer('/tmp/socket.server'); $encoder = new RemoteObjects\Encode\JsonRpc20Encoder(); $target = new RemoteObject(); $server = new RemoteObjects\Server( $transport, $encoder, $target ); $server->handle();
client.php
$transport = new RemoteObjects\Transport\UnixSocketClient('/tmp/socket.client', '/tmp/socket.server'); $encoder = new RemoteObjects\Encode\JsonRpc20Encoder(); $server = new RemoteObjects\Client( $transport, $encoder ); $result = $server->invoke('reply', 'Tristan'); echo $result; // -> "Hello Tristan"
Chaining and deep structure
Inspired from another JSON-RPC library, RemoteObjects allow complex structures on the server side. Sometimes you need a complex remote api, but you won't to overload your remote object class. Instead of creating multiple endpoints, it's possible to create multiple "named" remote objects.
Creating named objects is realy easy:
$server = new RemoteObjects\Server( $transport, $encoder, array( 'a' => $targetA, 'b' => $targetB ) );
To call methods from $targetA
or $targetB
you just have to prefix the method name with the object name, concatenated with a dot.
$client->invoke('a.methodA'); // invoke $targetA->methodA(); $client->invoke('b.methodB'); // invoke $targetB->methodB();
It is also possible to make bigger, more complex and multidimensional structures.
$server = new RemoteObjects\Server( $transport, $encoder, array( 'a' => array( 'one' => $targetOne, 'two' => array( 'I' => $targetI, 'II' => $targetII ) ), 'b' => $targetB ) );
To call $targetII->method()
for example, the method name will be a.two.II.method
.
Hint: You can also use ArrayAccess
compatible objects, instead of arrays!
For better and more programmatic chaining, is is possible to access the structure by virtual attributes of the RemoteObject
objects.
Accessing a property of RemoteObject
will give you a new RemoteObject
instance to this named path (similar to Client::getRemoteObject(<name>)
).
According to the previous example, access to a.two.II.method
is also possible this way:
$result = $client ->castAsRemoteObject() ->a ->two ->II ->method();
Lazy objects
In the last chapter, you read about chaining and deep structures.
But if your API grows up, creating all target objects may waste a lot of resources.
Instead of using arrays or ArrayAccess
objects, you can make a class with getters for the named objects.
class Objects { public function getA() { return new TargetA(); } public function getB() { return new TargetB(); } }
And then use this object as target.
$server = new RemoteObjects\Server( $transport, $encoder, new Objects() );
To access methods from TargetA
or TargetB
it is the same as before,
use a.methodName
to invoke TargetA::methodName
or b.methodName
to invoke TargetB::methodName
.
Remote object accessors
RemoteObjects allow to create RemoteObject
objects to directly call the methods on it.
On the server side:
$server = new RemoteObjects\Server( $transport, $encoder, array( 'a' => $targetA, 'b' => $targetB ) );
On the client side:
$remoteA = $client->getRemoteObject('a'); $remoteB = $client->getRemoteObject('b');
Now $remoteA
is an accessor to $targetA
and $remoteB
to $targetB
.
Keep in mind that $remoteA
and $remoteB
are just proxies without any methods.
Every method is dynamically passed to the server side.
If you don't have named objects on the server side, you can also pack the complete client object as RemoteObject
.
$remote = $client->castAsRemoteObject();
Now every call $remote->method($arg1, $arg2, ...)
will directly passed to $client->invokeArgs('method', [$arg1, $arg2, ...])
.
Type mapping
One big problem of remote method invocation, and the previous shown method is the nescience of the remote methods.
Every object you get with Client::getRemoteObject
or Client::castAsRemoteObject
is just a primitive proxy, without any methods.
You are unable to use method_exists
or ReflectionClass
to "inspect" the object and its methods.
To solve this problem, RemoteObjects allow you to specify a type, to use as RemoteObject
.
Just specify your type, when calling Client::getRemoteObject
or Client::castAsRemoteObject
.
interface MyRemote { public function remoteMethod(); } $remote = $client->castAsRemoteObject('MyRemote');
Since version 1.2 you can also use a class.
class MyRemote { public function remoteMethod() { // ... } } $remote = $client->castAsRemoteObject('MyRemote');
The object $remote
is an instance of MyRemote
, but it is also an instance of RemoteObjects\RemoteObject
.
How this works?
Internally a virtual temporary proxy class is generated, named RemoteProxies\__WS__\MyRemote
(the namespace is prefixed, in previous version the class name was suffixed) that implements the interface.
With this technique you can make nearly every object remote and pass the object to other methods without type hint mismatch. All you need is an interface.
Known limitations
- Pass parameters by reference is impossible for remote objects.
- Parameters that are unable to be serialized cannot be transported to the remote endpoint.
Security
Sometimes you want to increase security, but your transport layer does not support encryption (for example you cannot use HTTPS for some reason).
RemoteObjects provides an AesEncoder
and a RsaEncoder
that encrypt the data before transport and decode before evaluation.
Using the AesEncoder
or RsaEncoder
, is really simple.
AES
Server and client:
$jsonEncoder = new RemoteObjects\Encode\JsonRpc20Encoder(); $encoder = new RemoteObjects\Encode\AesEncoder( $jsonEncoder, '<add your pre-shared key here>' );
RSA
Server:
$jsonEncoder = new RemoteObjects\Encode\JsonRpc20Encoder(); $encoder = new RemoteObjects\Encode\RsaEncoder( $jsonEncoder, '<add client public key here>', '<add server private key here>' );
Client:
$jsonEncoder = new RemoteObjects\Encode\JsonRpc20Encoder(); $encoder = new RemoteObjects\Encode\RsaEncoder( $jsonEncoder, '<add server public key here>', '<add client private key here>' );
Logging
Monolog is supported, but not required. You can add a logger to each transport, encoder or server/client object to log errors and debug informations.
$logger = new \Monolog\Logger('RemoteObjects'); $logger->pushHandler(new StreamHandler('php://stderr', Logger::ERROR)); $transport->setLogger($logger); $encoder->setLogger($logger); $server->setLogger($logger); // or $client->setLogger($logger);