README

The Jsonrpc plugin for CakePHP provides server and client implementations of JSON-RPC.

Requirements

CakePHP 2+
PHP 5.3+

Installation

To use the plugin simply include it in your application's "app/Plugin" directory, and load it in the "app/Config/bootstrap.php" file.

CakePlugin::load('Jsonrpc');

The above code is not required if you're already using CakePlugin::loadAll() to load all plugins.

Implementation

Server

The Jsonrpc.Server component allows a CakePHP application to listen for incoming JSON-RPC calls. The actions listening are defined in the "listen" option of the component's settings. To add the component to your controller acting as the end-point include it in your $components property, for example:

public $components = array(
	'Jsonrpc.Server' => array(
		'listen' => array('example') // will process JSON-RPC requests sent to this action
	)
);

Once available, the server will now listen on the actions specified in the "listen" setting. When a call is made to one of these actions, and assuming no error occurs previously in the processing of the request, the call will be delegated to the controller method defined in the "method" property of the JSON request object. This method will receive a single argument, which is the JSON request object received by the server. The value returned by this method will be JSON encoded, and sent back to the client in the "result" property of the JSON response object.

public function user($request) {
	if (isset($request->params->userId)) {
		return $this->User->findById($request->params->userId);
	} else {
		throw new Exception('No user ID was specified', 123);
	}
);

In order to send an error as the response you need only throw an Exception in your controller's method. This will be caught by the Server component and processed as a JSON error object.

Client

The Jsonrpc.Client component allows a CakePHP application to make JSON-RPC requests to a server. To use the component add it to the $components property of your controller, for example:

public $components = array('Jsonrpc.Client');

From your actions you can now make requests using the Client component. To do so, first create a JSON request object, and then send it to the JSON-RPC server.

public function getUser() {
	// create a JSON request object
	$request = $this->Client->createJsonRequest('user', array('userId' => 7));
	// send the request to the server and return the result
	return $this->Client->sendJsonRequest($request, array('host' => 'example.com', 'path' => '/api/call'));
);

Keep in mind that if a JSON error object is returned from the server this will be thrown as a CakeException in your application.

You can also send batch requests to a server by specifying multiple JSON request objects in an array, for example:

public function getAllTheThings() {
	// create multiple JSON request objects in an array
	$batch = array(
		$this->Client->createJsonRequest('hat', array('hatId' => 11)),
		$this->Client->createJsonRequest('jacket', array('jacketId' => 55)),
		$this->Client->createJsonRequest('shoes', array('shoesId' => 73))
	);
	// send the array of requests to the server and return the results as an array
	return $this->Client->sendJsonRequest($batch);
);

When sending batch requests, if one of the request returns a JSON error object a CakeException will not be thrown, as the error object is returned within the array. Also, be aware that the order of the JSON response objects may not be coherent with the order of the requests sent, so always use the ID to determine the response corresponding with your request.

Documentation

For a full reference on the internals of the JSON-RPC protocol/transport see the specification.

Support

For support, bugs and feature requests, please use the issues section of this repository.

Contributing

If you'd like to contribute new features, enhancements or bug fixes to the code base just follow these steps:

Create a GitHub account, if you don't own one already
Then, fork the Jsonrpc plugin repository to your account
Create a new branch from the develop branch in your forked repository
Modify the existing code, or add new code to your branch, making sure you follow the CakePHP Coding Standards
Modify or add unit tests which confirm the correct functionality of your code (requires PHPUnit 3.5+)
Consider using the CakePHP Code Sniffer to check the quality of your code
When ready, make a pull request to the main repository

There may be some discussion reagrding your contribution to the repository before any code is merged in, so be prepared to provide feedback on your contribution if required.

A list of contributors to the Jsonrpc plugin can be found here.

Licence

Licensed under the MIT License. Redistributions of the source code included in this repository must retain the copyright notice found in each file.

Acknowledgements

Thanks to Larry Masters and everyone who has contributed to CakePHP, helping make this framework what it is today. Also, to the JSON-RPC Working Group, for their hard work and dedication to the specification.

jameswatts / cake-jsonrpc

Maintainers

Details