README

一个智能REST客户端，具有直观的API，提供所有REST方法，并返回Symfony响应对象。

动机

有些Symfony2包提供REST请求的抽象，但没有一个让人感觉“这正是我所需要的”！过去使用了一些这些包，我们总是不得不改进或重新映射它们的API来满足我们的需求。

前几天我们再次面临了同样的令人沮丧的挑战，并开始冥想我们具体的API需求并不那么特别。所以我们质疑自己，一个简单的REST-Client-API应该是什么样子

$restclient->post($url, $payload);
$restclient->get($url);
$restclient->put($url, $payload);
$restclient->delete($url);

另一个担忧是许多其他包在输出方面的抽象泄漏：它们将PHP原生的curl-addon API映射到面向对象的接口，只是为了让我们处理curl API调用的非面向对象的原始输出。在这个时候，，使用（极其不便的）PHP内部curl API会更方便。

但是输出应该如何封装呢？

• 所以，访问这个页面，你很可能是Symfony开发者
• 因此，我们可以推断出你知道Symfony响应对象

因此，Symfony响应对象是我们的选择：我们不需要推出自己的实现，可以保持在我们选择的框架的范围内——双赢 :-)

所以总的来说，今天就到这里，让我们开始使用这个包。

安装

步骤1：使用composer下载包

运行以下命令添加包

php composer.phar require ci/restclientbundle

Composer会将包安装到你的项目的vendor/ci目录。

步骤2：启用包

在symfony内核中启用包

<?php
// PROJECTROOT/app/AppKernel.php

public function registerBundles()
{
    $bundles = array(
        // ...
        new Circle\RestClientBundle\CircleRestClientBundle(),
    );
}

配置

该包允许您配置底层PHP内部curl库提供的所有默认选项——使用它们的真实名称。无需重映射重映射重映射：D

名称及其可能值可以在此处找到：https://php.ac.cn/manual/de/function.curl-setopt.php

您可以通过向您的app/config.yml添加以下行来更改配置

circle_rest_client:
    curl:
      defaults:
        $optionName: $value
        $optionName: $value
        ...

示例

circle_rest_client:
    curl:
      defaults:
        CURLOPT_HTTPHEADER:     [ 'Content-Type: application/json' ]
        CURLOPT_FOLLOWLOCATION: true

将请求头设置为application/json并跟随重定向。

异常

您不能更改CURLOPT_RETURNTRANSFER的默认值（默认=true）。

使用

$restClient = $this->container->get('circle.restclient');

$restClient->get('http://www.someUrl.com');
$restClient->post('http://www.someUrl.com', 'somePayload');
$restClient->put('http://www.someUrl.com', 'somePayload');
$restClient->delete('http://www.someUrl.com');
$restClient->patch('http://www.someUrl.com', 'somePayload');

$restClient->head('http://www.someUrl.com');
$restClient->options('http://www.someUrl.com', 'somePayload');
$restClient->trace('http://www.someUrl.com');
$restClient->connect('http://www.someUrl.com');

异常处理

由于REST客户端使用libcurl，我们为每个libcurl错误创建了一个异常类。查看完整的错误列表：[http://curl.haxx.se/libcurl/c/libcurl-errors.html](http://curl.haxx.se/libcurl/c/libcurl-errors.html) 表示libcurl错误的异常类具有以下命名约定

• 想象有一个名为CURLE_OPERATION_TIMEDOUT的错误
• 首先删除CURLE_前缀：CURLE_OPERATION_TIMEDOUT --> OPERATION_TIMEDOUT
• 然后将拼写改为驼峰式：OPERATION_TIMEDOUT --> OperationTimedOut
• 添加后缀"Exception"：OperationTimedOut --> OperationTimedOutException
• OperationTimedOutException是与libcurl错误CURLE_OPERATION_TIMEDOUT对应的异常

知道所有这些异常的存在可以极大地改善异常处理

try {
  $restClient->get('http://www.someUrl.com');
} catch (Circle\RestClientBundle\Exceptions\OperationTimedOutException $exception) {
  // do something
}

如果您仍然想要捕获所有REST异常，则可以捕获基本的libcurl异常

try {
  $restClient->get('http://www.someUrl.com');
} catch (Circle\RestClientBundle\Exceptions\CurlException $exception) {
  // do something
}

高级使用

您可以通过添加一个键值存储的选项数组来添加额外的选项来自定义特定的请求。

$restClient = $this->container->get('circle.restclient');

$restClient->get('http://www.someUrl.com', array(CURLOPT_CONNECTTIMEOUT => 30));
$restClient->post('http://www.someUrl.com', 'somePayload', array(CURLOPT_CONNECTTIMEOUT => 30));
$restClient->put('http://www.someUrl.com', 'somePayload', array(CURLOPT_CONNECTTIMEOUT => 30));
$restClient->delete('http://www.someUrl.com', array(CURLOPT_CONNECTTIMEOUT => 30));

$restClient->head('http://www.someUrl.com', array(CURLOPT_CONNECTTIMEOUT => 30));
$restClient->options('http://www.someUrl.com', 'somePayload', array(CURLOPT_CONNECTTIMEOUT => 30));
$restClient->trace('http://www.someUrl.com', array(CURLOPT_CONNECTTIMEOUT => 30));
$restClient->connect('http://www.someUrl.com', array(CURLOPT_CONNECTTIMEOUT => 30));

测试包

可以通过phpunit测试包。

前提条件

• 必须通过composer安装供应商
• （当然）必须安装PHPUnit
• 本地机器上不得阻止端口8000
• 应启用XDebug

正在执行测试

测试是在位于Tests/TestServer文件夹的本地php服务器上执行的。通过以下命令执行测试

make

路线图

• 针对REST方法等有严格的规则，例如服务器不得在HEAD请求的响应中返回消息体
• 事件处理（onRequest, preRequest, postRequest）