README

关于 Fetch PHP

FetchPHP 是一个 PHP 库，使用强大的 Guzzle HTTP 客户端模拟 JavaScript 的 fetch API 的行为。FetchPHP 支持同步和异步请求，并提供一个易于使用、灵活的 API，用于在 PHP 中进行 HTTP 请求。

安装

要安装 FetchPHP，请运行以下命令

composer require jerome/fetch-php

核心函数概述

FetchPHP 提供了三个主要函数

1. fetch – 执行一个 同步 HTTP 请求。
2. fetch_async – 执行一个 异步 HTTP 请求，并返回一个 Guzzle PromiseInterface。
3. fetchAsync – fetch_async 的别名，但已被 弃用。

自定义 Guzzle 客户端使用

默认情况下，FetchPHP 使用一个单例 Guzzle 客户端实例，该实例在所有请求之间共享。但是，您可以通过 fetch 和 fetch_async 的 options 参数提供自己的 Guzzle 客户端。这使您能够完全控制客户端配置，包括基础 URI、头信息、超时等。

如何提供自定义 Guzzle 客户端

<?php

use GuzzleHttp\Client;

// Create a singleton instance of Guzzle client
$client = new Client([
    'base_uri' => 'https://jsonplaceholder.typicode.com',
    'timeout' => 10.0,
    // Other default options
]);

// Pass the Guzzle client into the fetch function via options
$response = fetch('/todos/1', [
    'client' => $client
]);

$response2 = fetch('/todos/2', [
    'client' => $client
]);

print_r($response->json());
print_r($response2->json());

为什么使用单例？

传递单例 Guzzle 客户端在以下情况下很有用：

• 您正在执行许多请求，并希望避免每次创建新客户端的开销。
• 您想要配置特定的客户端级选项（例如，基础 URI、超时、头信息）并在多个请求中重用它们。

1. 使用 fetch 进行同步请求

fetch 函数执行 HTTP 请求，并返回一个 Response 对象，该对象提供方便的方法来与响应交互。

基本 GET 请求示例

<?php

require 'vendor/autoload.php';

$response = fetch('https://jsonplaceholder.typicode.com/todos/1');

// Get the JSON response
$data = $response->json();
print_r($data);

// Get the status text (e.g., "OK")
echo $response->statusText();

可用的响应方法

基于 Guzzle 的 Psr7\Response 的 Response 类提供了各种方法来与响应数据交互

• json(bool $assoc = true)：将响应体解码为 JSON。如果 $assoc 为 true，则返回一个关联数组。如果 false，则返回一个对象。
• text()：返回响应体作为纯文本。
• blob()：返回响应体作为 PHP 流资源（如“blob”）。
• arrayBuffer()：返回响应体作为二进制字符串。
• statusText()：返回 HTTP 状态文本（例如，对于 200，“OK”）。
• ok()：如果状态码在 200-299 之间，则返回 true。
• isInformational()、isRedirection()、isClientError()、isServerError()：检查状态范围的辅助方法。

2. 使用 fetch_async 进行异步请求

fetch_async 函数返回一个 PromiseInterface 对象。您可以使用 .then() 和 .wait() 方法来管理异步流程。

基本异步 GET 请求示例

<?php

require 'vendor/autoload.php';

$promise = fetch_async('https://jsonplaceholder.typicode.com/todos/1');

$promise->then(function ($response) {
    $data = $response->json();
    print_r($data);
});

// Wait for the promise to resolve
$promise->wait();

异步请求中的错误处理

您可以使用承诺的 then 或 catch 方法来处理错误

$promise = fetch_async('https://nonexistent-url.com');

$promise->then(function ($response) {
    // handle success
}, function ($exception) {
    // handle failure
    echo "Request failed: " . $exception->getMessage();
});

$promise->wait();

请求选项

FetchPHP 在 fetch 和 fetch_async 方法中接受一个选项数组作为第二个参数。这些选项配置了请求的处理方式。

可用的请求选项

• method：HTTP 方法（例如，'GET'、'POST'、'PUT'、'DELETE'）。默认是 'GET'。
• headers：HTTP 头部数组（例如，['Authorization' => 'Bearer token']）。
• body：POST、PUT、PATCH 请求的请求体。
• json：要作为请求体发送的 JSON 数据。自动设置 Content-Type: application/json。
• multipart：用于文件上传的多部分表单数据数组。
• query：查询参数的关联数组。
• timeout：秒数超时。默认是 10。
• allow_redirects：是否跟随重定向（true/false）。默认是 true。
• cookies：布尔值以启用 cookies。如果 true，则使用新的 CookieJar。您还可以传递 GuzzleHttp\Cookie\CookieJar 的实例。
• auth：用于 HTTP Basic 或 Digest 认证的数组。
• proxy：用于路由请求的代理服务器 URL。
• client：用于多个请求的重用自定义 Guzzle 客户端实例（例如，单例）。

高级用法示例

1. 带有 JSON 数据的 POST 请求

<?php

$response = fetch('https://jsonplaceholder.typicode.com/posts', [
    'method' => 'POST',
    'json' => [
        'title' => 'My Post',
        'body' => 'This is the body of the post',
        'userId' => 1,
    ],
]);

print_r($response->json());

2. 带有查询参数的 GET 请求

<?php

$response = fetch('https://jsonplaceholder.typicode.com/posts', [
    'query' => ['userId' => 1],
]);

print_r($response->json());

3. 带有多部分数据的文件上传

<?php

$response = fetch('https://example.com/upload', [
    'method' => 'POST',
    'multipart' => [
        [
            'name' => 'file',
            'contents' => fopen('/path/to/file.jpg', 'r'),
            'filename' => 'file.jpg'
        ],
    ]
]);

echo $response->statusText();

错误处理

FetchPHP 优雅地处理错误，当请求失败时，在响应中返回 500 状态码和错误消息。

同步请求中的错误处理

<?php

$response = fetch('https://nonexistent-url.com');

echo $response->getStatusCode();  // Outputs 500
echo $response->text();  // Outputs error message

异步请求中的错误处理

<?php

$promise = fetch_async('https://nonexistent-url.com');

$promise->then(function ($

response) {
    echo $response->text();
}, function ($exception) {
    echo "Request failed: " . $exception->getMessage();
});

$promise->wait();

代理支持

FetchPHP 允许使用 proxy 选项通过代理服务器路由请求。

<?php

$response = fetch('https://example.com', [
    'proxy' => 'tcp://:8080'
]);

echo $response->statusText();

认证

您可以使用 auth 选项指定 HTTP Basic 或 Digest 认证。

<?php

$response = fetch('https://example.com/secure-endpoint', [
    'auth' => ['username', 'password']
]);

echo $response->statusText();

与响应对象协同工作

Response 类提供了方便的方法来与响应体、头部和状态码交互。

响应方法概述

• json()：将响应体解码为 JSON。
• text()：返回原始的响应体作为纯文本。
• blob()：将体作为 PHP 流返回（对于文件处理很有用）。
• arrayBuffer()：将体作为二进制字符串返回。
• statusText()：返回状态文本（例如，“OK”）。
• ok()：如果状态是 200-299，则返回 true。

示例：访问响应数据

<?php

$response = fetch('https://jsonplaceholder.typicode.com/todos/1');

// Get the response body as JSON
$data = $response->json();
print_r($data);

// Get the status text (e.g., "OK")
echo $response->statusText();

综合用法示例

<?php

require 'vendor/autoload.php';

// POST request with JSON data, custom headers, query parameters, and authentication
$response = fetch('https://api.example.com/data', [
    'method' => 'POST',
    'headers' => [
        'Authorization' => 'Bearer YOUR_TOKEN',
        'Custom-Header' => 'MyHeaderValue'
    ],
    'query' => ['param1' => 'value1'],
    'json' => ['key' => 'value'],
    'auth' => ['username', 'password'],
    'timeout' => 10,
    'allow_redirects' => true
]);

if ($response->ok()) {
    // Print the JSON response
    print_r($response->json());
} else {
    echo "Error: " . $response->statusText();
}

许可

本项目采用 MIT 许可证 - 详细信息请参阅 LICENSE.md 文件。

贡献

贡献使得开源社区成为学习、灵感和创作的绝佳场所。您所做出的任何贡献都将被 高度赞赏。

如果您有改进此项目的建议，请分叉存储库并创建一个拉取请求。您还可以简单地创建一个带有“enhancement”标签的问题。

别忘了给这个项目加星！再次感谢！

1. 分叉项目
2. 创建您的功能分支（git checkout -b feature/amazing-feature）
3. 提交您的更改（git commit -m 'Add some amazing-feature'）
4. 将更改推送到分支（git push origin feature/amazing-feature）
5. 打开一个拉取请求

作者

• [Jerome Thayananthajothy] - 初始工作 - Thavarshan

请参阅参与此项目的贡献者列表。

致谢

• 感谢Guzzle HTTP的Guzzle包，它为此项目提供了基础。