README

simple-json-rpc-client

这是一个简单而强大的JSON-RPC客户端，它完全实现了JSON-RPC 2.0规范。它提供了一个用于创建自定义客户端的接口，并附带了一个默认实现，该实现通过POST方式在HTTP上发送请求。作为符合标准的客户端，它支持标准请求、通知以及批量请求。

要求

需要PHP 5.4。

安装

使用Composer安装（该软件包已在Packagist上发布）。如果您不需要运行测试套件，请使用--no-dev选项进行安装。

使用方法

标准请求

<?php

use SimpleJsonRpcClient\Client\HttpPostClient as Client;

use SimpleJsonRpcClient\Request\Request;
use SimpleJsonRpcClient\Exception\BaseException;
use SimpleJsonRpcClient\Response\Response;

// Initialize the client. Credentials are optional.
$client = new Client('localhost', 'username', 'password');

try 
{
	// Send a request without parameters. The "id" will be added automatically unless supplied.
	// Request objects return their JSON representation when treated as strings.
	$request = new Request('method');
	$response = $client->sendRequest($request);
	
	// Send a request with parameters specified as an array
	$request = new Request('method', array('param1'=>'value1'));
	$response = $client->sendRequest($request);
	
	// Send a request with parameters specified as an object
	$params = new stdClass();
	$params->param1 = 'value1';
	$request = new Request('method', $params);
	$response = $client->sendRequest($request);
	
	// Send a parameter-less request with specific "id"
	$request = new Request('method', null, 2);
	$response = $client->sendRequest($request);
}
catch (BaseException $e) 
{
	echo $e->getMessage();
}

通知

<?php

use SimpleJsonRpcClient\Client\HttpPostClient as Client;

use SimpleJsonRpcClient\Request\Notification;
use SimpleJsonRpcClient\Exception\BaseException;

$client = new Client('localhost', 'username', 'password');

try 
{
	$request = new Notification('notification');
	$client->sendNotification($request);
}
catch (BaseException $e) 
{
	echo $e->getMessage();
}

批量请求

<?php

use SimpleJsonRpcClient\Client\HttpPostClient as Client;

use SimpleJsonRpcClient\Request;
use SimpleJsonRpcClient\Exception\BaseException;

$client = new Client('localhost', 'username', 'password');

try 
{
	$request = new Request\BatchRequest(array(
		new Request\Request('method'),
		new Request\Notification('anotherMethod'),
		new Request\Request('yetAnotherMethod', null, 3)
	));
	
	$batchResponse = $client->sendBatchRequest($request);
	
	// Retrieve all response objects
	$responses = $batchResponse->getResponses();
	
	// Get specific response
	$response = $batchResponse->getResponse(3);
}
catch (BaseException $e) 
{
	echo $e->getMessage();
}

异常处理

所有异常都派生自基类BaseException。如果您不想将特定异常与其他异常区别对待，您只需像上面示例中那样捕获BaseException即可。下面是一个说明异常层次结构的示例。

<?php

use SimpleJsonRpcClient\Client\HttpPostClient as Client;

use SimpleJsonRpcClient\Request;
use SimpleJsonRpcClient\Exception;
use SimpleJsonRpcClient\Response;

$client = new Client('localhost', 'username', 'password');

try 
{
	$request = new Request\Request('method', array('param1'=>'value1'));
	$response = $client->sendRequest($request);
}
catch (ClientException $ce) {
	// The client failed to execute the request
}
catch (InvalidResponseException $e) 
{
	// The response was invalid, e.g. it could not be parsed or it is not standard-compliant
}
catch (ResponseErrorException $re) {
	// The request itself was successful but the JSON-RPC response indicates an error.
	// A subclass of ResponseErrorException is thrown for pre-defined errors (see http://www.jsonrpc.org/specification#error_object)
}
catch (Exception $e) {
	// Anything else, usually InvalidArgumentException
}

错误处理

某些JSON-RPC服务器可能在它们的响应错误中返回一个“data”属性。该属性可能包含有关错误性质的有价值信息。每当响应指示错误时，都会抛出特殊的ResponseErrorException。该异常有一个getData()方法，它返回错误数据的对象表示。

try {
	$response = $client->sendRequest($request);
}
catch(ResponseErrorException $e) {
	$data = $e->getData();
}

标志

客户端构造函数接受一个标志集合作为第四个参数。这些标志可以用来更改客户端的行为，在处理有缺陷的服务器时非常有用。例如，FLAG_ATTEMPT_UTF8_RECOVERY标志将导致Response类尝试通过在传递给json_decode()之前将原始响应重新编码为UTF-8来避免“响应中UTF-8格式错误”错误。只有在确定原始响应不是有效的UTF-8时，才会执行此操作。

测试套件

在项目根目录中运行vendor/bin/phpunit以运行单元测试。测试套件将在本地主机:8585上启动一个模拟JSON-RPC服务器，使用PHP的内部Web服务器。如果此端口在您的系统上不可用，您可以通过编辑phpunit.xml来更改它。

许可证

此代码根据新BSD许可证授权。