README

此库为远程对象模式提供REST适配器，该模式由ProxyManager项目实现。同时提供REST客户端以方便REST交互。

安装

php composer.phar require "fourmation/rest-remote-object:1.0.*"

Rest远程对象示例

在examples/目录中提供了一些示例：JIRA、ZenDesk、Xero、eWay、FlightStats和AgileZen！现在，您可以转换所有REST API为远程对象！

Rest适配器用法

远程对象代理是位于不同系统上的对象，但被用作本地可用的对象。

要使用REST远程对象，请为您的服务接口添加两个标签：@rest\http用于定义要使用的HTTP方法，@uri用于定义资源URI

interface UserServiceInterface
{
    /**
     * @rest\http GET
     * @rest\uri /users/%id
     * @param int $id
     * @return \Models\User
     */
    public function get($id);
}

这就完成了！现在您可以开始使用您的REST API了

use ProxyManager\Factory\RemoteObjectFactory;
use RestRemoteObject\Adapter\Rest as RestAdapter;
use RestRemoteObject\Client\Rest as RestClient;
use RestRemoteObject\Client\Rest\Format\Format;
use RestRemoteObject\Client\Rest\Format\HeaderFormatStrategy;

$client = new RestClient('http://my-company.com/rest');
$client->setFormatStrategy(new HeaderFormatStrategy(new Format(Format::JSON)));

$factory = RemoteObjectFactory(
    new RestAdapter(
        $client
    )
);

// proxy is your remote implementation
$proxy = $factory->createProxy('UserServiceInterface');

$user = $proxy->get(1); // The result is automatically converted to a `\Models\User` class.

var_dump($user->getName()); // 'Vincent'

Rest版本控制

本项目提供三种版本控制方式

• 版本控制包含在头部（推荐）
• 版本控制包含在URL中
• 版本控制包含在URL参数中

use ProxyManager\Factory\RemoteObjectFactory;
use RestRemoteObject\Adapter\Rest as RestAdapter;
use RestRemoteObject\Client\Rest as RestClient;
use RestRemoteObject\Client\Rest\Format\Format;
use RestRemoteObject\Client\Rest\Format\HeaderFormatStrategy;
use RestRemoteObject\Client\Rest\Versioning\HeaderVersioningStrategy;

$versioning = new HeaderVersioningStrategy('3.0');

$client = new RestClient('http://my-company.com/rest');
$client->setFormatStrategy(new HeaderFormatStrategy(new Format(Format::JSON)));
$client->setVersioningStrategy($versioning);

$factory = new RemoteObjectFactory(
    new RestAdapter(
        $client
    )
);

// proxy is your remote implementation
$proxy = $factory->createProxy('UserServiceInterface');

$user = $proxy->get(1); // A header "Rest-Version: v3" will be added

var_dump($user->getName()); // 'Vincent'

Rest身份验证

提供三种身份验证策略

• 查询身份验证（推荐）
• HTTP身份验证
• 简单令牌

您可以使用REST客户端轻松地使用身份验证

use ProxyManager\Factory\RemoteObjectFactory;
use RestRemoteObject\Adapter\Rest as RestAdapter;
use RestRemoteObject\Client\Rest as RestClient;
use RestRemoteObject\Client\Rest\Authentication\QueryAuthenticationStrategy;
use RestRemoteObject\Client\Rest\Format\Format;
use RestRemoteObject\Client\Rest\Format\HeaderFormatStrategy;

$queryAuth = new QueryAuthenticationStrategy();
$queryAuth->setPublicKey('12345689');
$queryAuth->setPrivateKey('qwerty');

$client = new RestClient('http://my-company.com/rest');
$client->setFormatStrategy(new HeaderFormatStrategy(new Format(Format::JSON)));
$client->setAuthenticationStrategy($queryAuth);

$factory = new RemoteObjectFactory(
    new RestAdapter(
        $client
    )
);

// proxy is your remote implementation
$proxy = $factory->createProxy('UserServiceInterface');

$user = $proxy->get(1); // Your request will be `http://my-company.com/rest/users/1?public_key=12345689&signature=aaa665b46e1060c6b7e5a6b5c891c37312149ece`

var_dump($user->getName()); // 'Vincent'

功能

要将功能应用于API请求，只需实现FeatureInterface并使用addFeature方法。以下是使用时间戳功能的示例

use ProxyManager\Factory\RemoteObjectFactory;
use RestRemoteObject\Adapter\Rest as RestAdapter;
use RestRemoteObject\Client\Rest as RestClient;
use RestRemoteObject\Client\Rest\Feature\Timestamp;
use RestRemoteObject\Client\Rest\Format\Format;
use RestRemoteObject\Client\Rest\Format\HeaderFormatStrategy;

$queryAuth = new QueryAuthenticationStrategy();
$queryAuth->setPublicKey('12345689');
$queryAuth->setPrivateKey('qwerty');

$client = new RestClient('http://my-company.com/rest');
$client->setFormatStrategy(new HeaderFormatStrategy(new Format(Format::JSON)));
$client->addFeature(new TimestampFeature());

$factory = new RemoteObjectFactory(
    new RestAdapter(
        $client
    )
);

// proxy is your remote implementation
$proxy = $factory->createProxy('UserServiceInterface');

$user = $proxy->get(1); // Your request will be `http://my-company.com/rest/locations/1?t=1383881696`

var_dump($user->getName()); // 'Vincent'

自定义响应解析器

提供两种响应解析器：XML和JSON。解析器会根据响应格式自动选择。您可以编写自己的解析器，只需实现RestRemoteObject\Client\Rest\ResponseHandler\Parser\ParserInterface接口

interface ParserInterface
{
    /**
     * Parse response content
     *
     * @param $content
     * @return array
     */
    public function parse($content);
}

使用您的解析器如下

use ProxyManager\Factory\RemoteObjectFactory;
use RestRemoteObject\Adapter\Rest as RestAdapter;
use RestRemoteObject\Client\Rest as RestClient;
use RestRemoteObject\Client\Rest\Format\Format;
use RestRemoteObject\Client\Rest\Format\HeaderFormatStrategy;

$client = new RestClient('http://my-company.com/rest');
$client->setFormatStrategy(new HeaderFormatStrategy(new Format(Format::JSON)));

$responseHandler = $client->getResponseHandler();
$responseHandler->getResponseParser(new MyParser()); // create your own logic here

$factory = new RemoteObjectFactory(
    new RestAdapter(
        $client
    )
);

// proxy is your remote implementation
$proxy = $factory->createProxy('UserServiceInterface');

$user = $proxy->get(1);

var_dump($user->getName()); // 'Vincent'

自定义响应构建器

提供两种标准构建器：DefaultBuilder和GhostObjectBuilder。

DefaultBuilder将数据（由响应解析器提供）转换为对象。默认情况下，将使用ClassMethods填充器，因此如果您已定义getter/setter，对象将很容易构建。

第二个构建器是GhostObjectBuilder，它提供一个代理对象（通过setter/getter，类似于DefaultBuilder）而不是真实对象，并允许从未初始化的属性进行远程调用。

use ProxyManager\Factory\RemoteObjectFactory;
use RestRemoteObject\Adapter\Rest as RestAdapter;
use RestRemoteObject\Client\Rest as RestClient;
use RestRemoteObject\Client\Rest\Format\Format;
use RestRemoteObject\Client\Rest\Format\HeaderFormatStrategy;

$client = new RestClient('http://my-company.com/rest');
$client->setFormatStrategy(new HeaderFormatStrategy(new Format(Format::JSON)));

$responseHandler = $client->getResponseHandler();
$responseHandler->setResponseBuilder(new GhostObjectBuilder($this->restClient));

$factory = new RemoteObjectFactory(
    new RestAdapter(
        $client
    )
);

// proxy is your remote implementation
$proxy = $factory->createProxy('UserServiceInterface');

$user = $proxy->get(1);

var_dump($user->getName()); // 'Vincent' -- local data
var_dump($user->getLocations()); // will call remote method !

要实现远程调用，只需在您的模型中定义您的注解即可

class User
{
    public function getId()
    {
        return $this->id;
    }

    /**
     * @rest\http GET
     * @rest\uri /locations?user=:getId
     * @rest\mapping setLocations
     * @return \RestRemoteObjectTestAsset\Models\Location[]
     */
    public function getLocations()
    {
        return $this->locations;
    }

    public function setLocations(array $locations)
    {
        $this->locations = $locations;
    }
}