苏东岩/json-rpc

简单易用的 Json-RPC 客户端/服务器库

维护者

详细信息

github.com/sudongyan/JsonRPC

主页

源代码

安装: 39

依赖: 0

建议者: 0

安全: 0

星星: 0

关注者: 2

分支: 153

v1.2.7 2018-10-10 04:55 UTC

Requires

  • php: >=5.4

Requires (Dev)

MIT 661e1c07a78cf508aff4f377197deb0293a784df

  • Frédéric Guillot

This package is auto-updated.

Last update: 2024-09-10 20:14:59 UTC

README

一个简单易用的 Json-RPC 客户端/服务器

完全基于 fguillot/JsonRPC 的版本，包含最新更改。

特性

  • 仅支持 JSON-RPC 2.0
  • 服务器支持批量请求和通知
  • 基于认证和 IP 的客户端限制
  • 自定义中间件
  • 全面单元测试
  • 要求：PHP >= 5.4
  • 许可证：MIT

作者

弗德里克·纪尧姆

使用 Composer 安装

对于 PHP >= 5.4

composer require fguillot/json-rpc

对于 PHP 5.3（最后一个支持版本）

composer require fguillot/json-rpc 1.2.5

示例

服务器

回调绑定

<?php

use JsonRPC\Server;

$server = new Server();
$server->getProcedureHandler()
    ->withCallback('addition', function ($a, $b) {
        return $a + $b;
    })
    ->withCallback('random', function ($start, $end) {
        return mt_rand($start, $end);
    })
;

echo $server->execute();

从数组进行回调绑定

<?php

use JsonRPC\Server;

$callbacks = array(
    'getA' => function() { return 'A'; },
    'getB' => function() { return 'B'; },
    'getC' => function() { return 'C'; }
);

$server = new Server();
$server->getProcedureHandler()->withCallbackArray($callbacks);

echo $server->execute();

类/方法绑定

<?php

use JsonRPC\Server;

class Api
{
    public function doSomething($arg1, $arg2 = 3)
    {
        return $arg1 + $arg2;
    }
}

$server = new Server();
$procedureHandler = $server->getProcedureHandler();

// Bind the method Api::doSomething() to the procedure myProcedure
$procedureHandler->withClassAndMethod('myProcedure', 'Api', 'doSomething');

// Use a class instance instead of the class name
$procedureHandler->withClassAndMethod('mySecondProcedure', new Api, 'doSomething');

// The procedure and the method are the same
$procedureHandler->withClassAndMethod('doSomething', 'Api');

// Attach the class, the client will be able to call directly Api::doSomething()
$procedureHandler->withObject(new Api());

echo $server->execute();

从数组进行类/方法绑定

<?php

use JsonRPC\Server;

class MathApi
{
    public function addition($arg1, $arg2)
    {
        return $arg1 + $arg2;
    }

    public function subtraction($arg1, $arg2)
    {
        return $arg1 - $arg2;
    }

    public function multiplication($arg1, $arg2)
    {
        return $arg1 * $arg2;
    }

    public function division($arg1, $arg2)
    {
        return $arg1 / $arg2;
    }
}

$callbacks = array(
    'addition'       => array( 'MathApi', addition ),
    'subtraction'    => array( 'MathApi', subtraction ),
    'multiplication' => array( 'MathApi', multiplication ),
    'division'       => array( 'MathApi', division )
);

$server = new Server();
$server->getProcedureHandler()->withClassAndMethodArray($callbacks);

echo $server->execute();

服务器中间件

中间件可用于对客户端进行认证和授权。它们在每次调用之前执行。

<?php

use JsonRPC\Server;
use JsonRPC\MiddlewareInterface;
use JsonRPC\Exception\AuthenticationFailureException;

class Api
{
    public function doSomething($arg1, $arg2 = 3)
    {
        return $arg1 + $arg2;
    }
}

class MyMiddleware implements MiddlewareInterface
{
    public function execute($username, $password, $procedureName)
    {
        if ($username !== 'foobar') {
            throw new AuthenticationFailureException('Wrong credentials!');
        }
    }
}

$server = new Server();
$server->getMiddlewareHandler()->withMiddleware(new MyMiddleware());
$server->getProcedureHandler()->withObject(new Api());
echo $server->execute();

当 API 凭证错误时，您可以抛出 AuthenticationFailureException，当用户无权访问程序时，您可以抛出 AccessDeniedException。

客户端

带有位置参数的示例

<?php

use JsonRPC\Client;

$client = new Client('https:///server.php');
$result = $client->execute('addition', [3, 5]);

带有命名参数的示例

<?php

use JsonRPC\Client;

$client = new Client('https:///server.php');
$result = $client->execute('random', ['end' => 10, 'start' => 1]);

参数按照正确顺序调用。

使用魔法方法 __call() 的示例

<?php

use JsonRPC\Client;

$client = new Client('https:///server.php');
$result = $client->random(50, 100);

上面的示例使用位置参数进行请求，而此示例使用命名参数。

$result = $client->random(['end' => 10, 'start' => 1]);

客户端批量请求

在单个 HTTP 请求中调用多个程序

<?php

use JsonRPC\Client;

$client = new Client('https:///server.php');

$results = $client->batch()
                  ->foo(['arg1' => 'bar'])
                  ->random(1, 100)
                  ->add(4, 3)
                  ->execute('add', [2, 5])
                  ->send();

print_r($results);

所有结果都存储在调用相同的同一位置。

客户端异常

客户端异常通常在服务器返回错误时抛出。您可以通过使用 $returnException 参数来更改此行为，这将导致返回异常。这在执行批量请求时非常有用。

  • BadFunctionCallException：服务器上找不到程序
  • InvalidArgumentException：程序参数错误
  • JsonRPC\Exception\AccessDeniedException：拒绝访问
  • JsonRPC\Exception\ConnectionFailureException：连接失败
  • JsonRPC\Exception\ServerErrorException：内部服务器错误

启用客户端调试

您可以通过启用调试模式来查看 JSON 请求和响应

<?php

use JsonRPC\Client;

$client = new Client('https:///server.php');
$client->getHttpClient()->withDebug();

调试输出发送到 PHP 系统日志记录器。您可以在 php.ini 中配置日志目标。

输出示例

==> Request:
{
    "jsonrpc": "2.0",
    "method": "removeCategory",
    "id": 486782327,
    "params": [
        1
    ]
}
==> Response:
{
    "jsonrpc": "2.0",
    "id": 486782327,
    "result": true
}

基于 IP 的客户端限制

服务器只能允许一些 IP 地址

<?php

use JsonRPC\Server;

$server = new Server;

// IP client restrictions
$server->allowHosts(['192.168.0.1', '127.0.0.1']);

[...]

// Return the response to the client
echo $server->execute();

如果客户端被阻止，您将收到一个 403 禁止的 HTTP 响应。

HTTP Basic 认证

如果您使用 HTTPS，您可以使用用户名/密码允许客户端。

<?php

use JsonRPC\Server;

$server = new Server;

// List of users to allow
$server->authentication(['user1' => 'password1', 'user2' => 'password2']);

[...]

// Return the response to the client
echo $server->execute();

在客户端，设置凭据如下

<?php

use JsonRPC\Client;

$client = new Client('https:///server.php');
$client->getHttpClient()
    ->withUsername('Foo')
    ->withPassword('Bar');

如果认证失败，客户端将抛出 RuntimeException。

使用替代认证头

use JsonRPC\Server;

$server = new Server();
$server->setAuthenticationHeader('X-Authentication');
$server->authentication(['myusername' => 'mypassword']);

上面的示例将使用 HTTP 头 X-Authentication 而不是标准的 Authorization: Basic [BASE64_CREDENTIALS]。用户名/密码值需要以 base64 编码：base64_encode('username:password')。

本地异常

默认情况下，服务器将所有异常都传递给客户端。如果您只想传递其中一些，请使用 Server::withLocalException($exception) 方法。

<?php

use JsonRPC\Server;
class MyException1 extends Exception {};
class MyException2 extends Exception {};

$server = new Server();

// Exceptions that should NOT be relayed to the client, if they occurs
$server
    ->withLocalException('MyException1')
    ->withLocalException('MyException2')
;

[...]

echo $server->execute();

客户端请求之前的回调

您可以使用回调在向服务器发出请求之前更改 HTTP 标头或 URL。

示例

<?php

$client = new Client();
$client->getHttpClient()->withBeforeRequestCallback(function(HttpClient $client, $payload) {
    $client->withHeaders(array('Content-Length: '.strlen($payload)));
});

$client->myProcedure(123);