README

efabrica/http-client 是一个 PHP 包，它提供了一个基于 Symfony 的 HttpClient 组件的简单高效的 HTTP 客户端。它增加了构造函数和方法中的命名参数，并提供了一个更易于静态分析的 API 来进行 HTTP 请求。如果 Symfony 改变了 HttpClient 组件，这个包将努力避免造成破坏性更改。

安装

您可以使用 Composer 安装此包。在您的项目根目录中运行以下命令

composer require efabrica/http-client

⚠️ 需要 PHP >=8.1。

用法

创建实例

要创建 HttpClient 类的实例，请使用 create 方法。此方法允许您配置 HTTP 客户端的各项选项，例如基本 URL、头信息、身份验证等。

use Efabrica\HttpClient\HttpClient;

// Create an instance with default options
$http = new HttpClient();

// Create an instance with custom options
$http = new HttpClient(
    baseUri: 'https://api.example.com',
    authBearer: 'your-access-token',
    timeout: 10.0,
    // ... other options
);

发送请求

HttpClient 类提供了用于发送不同类型 HTTP 请求的方法：GET、POST、PUT、PATCH、DELETE。

use Efabrica\HttpClient\HttpClient;

$http = new HttpClient('https://api.example.com', 'example_llt');

// Send a GET request
$response = $http->get('/resource', ['offset' => 0, 'limit' => 10]);

// Send a POST request with JSON payload
$response = $http->post('/resource', json: ['key' => 'value']);

// Send a POST request with FormData payload
$response = $http->post('/resource', body: ['key' => 'value']);

// Send a PUT request
$response = $http->put('https://api.example2.com/resource', ['email' => 'admin@example.com']);

// ... other request methods

处理异步响应

HttpClient 类返回实现了 Symfony 的 ResponseInterface 接口的 HttpResponse 对象。这允许您在不阻塞等待其方法被调用之前异步处理响应。

use Efabrica\HttpClient\HttpClient;

$http = new HttpClient();

// Send an asynchronous request (does not block)
$response = $http->get('https://api.example.com/resource');

// Access response asynchronously
// > Exceptions are thrown when the response is read
$response->getHttpCode(); // int|null       (does not block, returns null if response code is not available yet)
$response->getStatusCode(); // int          (blocks until response headers are available)
$response->getResponseHeaders(); // array   (blocks until response headers are available)
$response->getHeaders(); // array           (blocks until response headers are available) 
$response->getContent(); // string          (blocks until response body is available)
$response->toArray(); // JSON body as array (blocks until response body is available)

流式响应

您可以使用 stream 方法逐块生成完成的响应。

use Efabrica\HttpClient\HttpClient;

$http = new HttpClient();

// Send multiple requests and stream responses
$responses = [
    $http->get('https://api.example.com/resource1'),
    $http->get('https://api.example.com/resource2'),
    // ... add more requests
];

$stream = $http->stream($responses);

foreach ($stream as $response) {
    // Process each response asynchronously
}

添加装饰器

您可以通过添加装饰器来增强 HttpClient 的功能。装饰器可以修改或扩展底层 HTTP 客户端的行为。

use Efabrica\HttpClient\HttpClient;
use Symfony\Component\HttpClient\Decorator\CachedHttpClient;

$http = new HttpClient();

// Add a decorator to the HTTP client
$http->setClient(new BlackfiredHttpClient($http->getClient(), $blackfire));

// Create a new instance with an additional decorator
$blackfiredClient = $http->withClient(new BlackfiredHttpClient($http->getClient(), $blackfire));

更新选项

use Efabrica\HttpClient\HttpClient;

// Create an instance with default options
$http = new HttpClient();

// Create a new instance with updated options
$newHttp = $http->withOptions(baseUrl: 'https://api.new-example.com', /* ... */);

// Now $newHttp is a new instance of HttpClient with the updated options

此示例展示了如何使用 withOptions 方法创建具有更新选项的新 HttpClient 实例。原始的 HttpClient 实例保持不变。

贡献

欢迎贡献！如果您遇到任何问题或对改进有建议，请打开一个问题或提交一个拉取请求。