README

CakePHP 的 Jsonrpc 插件提供服务器和客户端的 JSON-RPC 实现。

需求

• CakePHP 2+
• PHP 5.3+

安装

要使用此插件，只需将其包含在应用程序的 "app/Plugin" 目录中，并在 "app/Config/bootstrap.php" 文件中加载它。

CakePlugin::load('Jsonrpc');

如果你已经使用 CakePlugin::loadAll() 来加载所有插件，则不需要上面的代码。

实现

服务器

Jsonrpc.Server 组件允许 CakePHP 应用程序监听传入的 JSON-RPC 调用。要添加该组件到控制器作为端点，将其包含在 $components 属性中，例如

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

一旦可用，服务器将监听 "listen" 设置中指定的动作。当调用这些动作之一时，如果请求处理过程中没有发生错误，则调用将被委托到 JSON 请求对象的 "method" 属性中定义的控制器方法。该方法将接收一个参数，即服务器接收到的 JSON 请求对象。该方法返回的值将被 JSON 编码，并通过 JSON 响应对象的 "result" 属性发送回客户端。

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);
	}
);

为了将错误作为响应发送，你只需在你的控制器方法中抛出一个 Exception。这将被 Server 组件捕获并处理为一个 JSON 错误对象。

客户端

Jsonrpc.Client 组件允许 CakePHP 应用程序向服务器发送 JSON-RPC 请求。要使用该组件，将其添加到控制器的 $components 属性中，例如

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

现在，你可以使用 Client 组件进行请求。为此，首先创建一个 JSON 请求对象，然后将其发送到 JSON-RPC 服务器。

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'));
);

请注意，如果服务器返回 JSON 错误对象，它将在你的应用程序中抛出 CakeException。

你还可以通过在数组中指定多个 JSON 请求对象来向服务器发送批处理请求，例如

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);
);

在发送批处理请求时，如果其中一个请求返回 JSON 错误对象，则不会抛出 CakeException，因为错误对象在数组中返回。此外，请注意，JSON 响应对象的顺序可能不会与发送请求的顺序一致，因此始终使用 ID 来确定与你的请求对应的响应。

文档

有关 JSON-RPC 协议/传输的内部结构的完整参考，请参阅 规范。

支持

有关支持、错误和功能请求，请使用此存储库的 问题 部分。

贡献

如果你想向代码库贡献新功能、增强功能或错误修复，请按照以下步骤操作

• 如果你还没有，创建一个 GitHub 账户
• 然后，将 fork Jsonrpc 插件仓库到您的账户
• 从您fork的仓库中的 develop 分支创建一个新的 分支
• 修改现有代码或向您的分支添加新代码，确保您遵循 CakePHP 编码规范
• 修改或添加 单元测试 以确认您的代码功能正确（需要 PHPUnit 3.5+）
• 考虑使用 CakePHP 代码规范检查器 来检查您的代码质量
• 准备好后，向主仓库提交 pull request

在代码合并之前，可能会有关于您对仓库贡献的讨论，所以请准备好在需要时提供对您的贡献的反馈。

可以在这里找到 Jsonrpc 插件的贡献者列表 这里。

许可

版权所有 2013 James Watts (CakeDC)。保留所有权利。

在 MIT 许可证下授权。包含在本仓库中的源代码的再分发必须保留每个文件中找到的版权声明。

致谢

感谢 Larry Masters 和 所有 为 CakePHP 做出贡献的人，帮助这个框架成为今天的样子。还要感谢 JSON-RPC 工作组，他们为规范所做的辛勤工作和奉献。