README

使用此库快速构建HTTP API的包装器

安装

使用composer将此添加到您的PHP项目中

composer require johnpbloch/fluent-http-api

用法

自定义配置

以下内容仅在你构建用于分发的库时才是必要的！

如果你将此代码库集成到其他项目中作为库（即作为其他项目的依赖项）使用，你应该创建自己的 \JohnPBloch\FluentApi\Config 和 \JohnPBloch\FluentApi\Endpoint 类的扩展，并确保初始化配置对象时将配置存储在自定义基本端点中。

// Custom Endpoint:

class MyEndpoint extends \JohnPBloch\FluentApi\Endpoint
{
    public static function setConfig(\JohnPBloch\FluentApi\Config $config): \JohnPBloch\FluentApi\Config
    {
        return self::$config = $config;
    }

    protected function getConfig() : \JohnPBloch\FluentApi\Config {
        return self::$config;
    }
}

// Custom Config

class MyConfig extends \JohnPBloch\FluentApi\Config
{
    protected function setConfigOnBaseEndpoint(): static
    {
        return MyEndpoint::setConfig($this);
    }
}

授权

此包提供了一些方法来向请求添加授权。 注意： 此库不处理身份验证，它假设你已经有可用的凭证来使用。以下授权方法可用：

• 基本认证
• 摘要认证
• NTLM认证
• Bearer令牌
• 头部键/值
• 查询键/值
• 基于Cookie的认证

基本认证

use JohnPBloch\FluentApi\Auth\BasicAuth;
$auth = new BasicAuth('username', 'password');

摘要认证

use JohnPBloch\FluentApi\Auth\DigestAuth;
$auth = new DigestAuth('username', 'password', 'digest');

NTLM认证

use JohnPBloch\FluentApi\Auth\NtlmAuth;
$auth = new NtlmAuth('username', 'password', 'ntlm');

Bearer令牌认证

仅包含令牌，不包含 Bearer 前缀。

use JohnPBloch\FluentApi\Auth\BearerAuth;
$auth = new BearerAuth('token');

头部键/值认证

use JohnPBloch\FluentApi\Auth\HeaderAuth;
$auth = new HeaderAuth('X-Header-Name', 'header value');

查询键/值认证

use JohnPBloch\FluentApi\Auth\QueryVariableAuth;
$auth = new QueryVariableAuth('query_var_name', 'token');

基于Cookie的认证

use JohnPBloch\FluentApi\Auth\CookieAuth;
$auth = new CookieAuth('cookie-name', 'cookie-value', 'domain.com');

初始化配置

在使用此库之前，您必须初始化配置对象。如果您为打包库扩展了Config对象，请使用该配置对象而不是 \JohnPBloch\FluentApi\Config。

use JohnPBloch\FluentApi\Config;

Config::initialize('https://api.some-domain.com/base-path/', $auth)

发送请求

使用 method() 方法设置HTTP请求方法（例如GET、POST等）

使用 path() 方法设置相对于配置基本URI的路径。

send() 方法将发送请求并返回一个PSR-7兼容的Guzzle响应。

此外，Endpoint类扩展了Laravel的 Fluent 类，并可以使用流畅方法向请求添加通用数据。默认情况下，GET、POST 和 PUT 将自动向请求添加流畅属性。 GET 数据将被添加到查询变量中；POST 和 PUT 请求将设置流畅属性为作为 application/x-www-form-urlencoded 请求的正文数据。如果您需要进一步调整请求，您需要扩展Endpoint以在发送之前进一步调整配置数据。

例如，一个简单的GET请求

use JohnPBloch\FluentApi\Endpoint;

$response = Endpoint::make()
    ->method('GET')
    ->path('resource/path')
    ->send();

或POST请求

use JohnPBloch\FluentApi\Endpoint;

$response = Endpoint::make()
    ->method('POST')
    ->path('article')
    ->title('This Article Will Change Your Life')
    ->content('<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Quisque commodo lacus et justo dictum, in imperdiet metus sagittis. Integer vestibulum justo quis tortor venenatis, a tempus justo pulvinar. Duis feugiat id orci ac condimentum. Fusce pellentesque dapibus tempus. Nulla nisi turpis, luctus sit amet enim sed, vulputate malesuada erat. Quisque varius quam eget sapien lobortis, ut vulputate nisl elementum. Proin sollicitudin eu ipsum vel mattis.</p>')
    ->send();

覆盖配置设置

如果您需要覆盖特定的配置选项，您可以扩展Endpoint类并设置公共或受保护的以覆盖值的方法。有两种类型的覆盖方法：setRequestConfig* 和 mergeRequestConfig*。对于每一种，Config 之后剩余的文本将确定将要设置的配置键。在使用之前，文本将被转换为蛇形小写。例如，名为 setRequestConfigFormParams() 的方法将设置Guzzle选项中的返回值为 form_params。

setRequestConfig* 方法将当前Guzzle选项作为唯一参数，并将方法返回值设置到Guzzle选项中。

mergeRequestConfig* 方法将返回值合并到现有（可能为空的）值中。这些方法没有输入。

在发送 Guzzle 请求之前，端点将调用 beforeSend($options)。 beforeSend 可以返回一个选项数组或一个 \Psr\Http\Message\ResponseInterface 对象。如果它返回一个选项数组，则请求将按预期发送。如果它返回一个响应对象，则将直接返回该对象，而不会发送请求或运行 afterSend 方法。

发送 Guzzle 请求后，响应对象将使用响应调用 afterSend()。 afterSend() 也必须返回一个响应，该响应将由 send() 返回。

许可证

根据 MIT 许可证授权。