README

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

动机

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

前几天我们又遇到了同样的令人沮丧的挑战，开始思考我们的特定 API 需求其实并不那么特别。于是我们问自己，一个简单的 REST 客户端 API 应该是什么样的

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

另一个问题是许多其他扩展提供的输出抽象过于松散：它们将 PHP 原生 cURL 扩展的 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 错误创建了一个异常类。请查看错误列表的完整列表：[libcurl 错误列表](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）