README

先决条件 | 安装 | 配置 | 使用 | 插件 | 事件 | 特性 | 建议 | 贡献 | 了解更多 | 许可

EightPoints GuzzleBundle for Symfony

此包将 Guzzle 6.x|7.x 集成到 Symfony。Guzzle 是一个用于构建 RESTful Web 服务客户端的 PHP 库。

GuzzleBundle 遵循语义化版本控制。更多关于 semver.org 的信息。

先决条件

• PHP 7.1 或更高版本
• Symfony 5.x 或 6.x 或 7.x

安装

安装包

要在命令行上安装此包，请运行以下命令，您将从 Packagist 获取最新稳定版本。

composer require eightpoints/guzzle-bundle

注意：此包有一个 Symfony Flex Recipe，可以自动将此包注册和配置到您的 symfony 应用程序中。

如果您的项目不使用 Symfony Flex，则需要手动将以下内容添加到 config/bundles.php 中

<?php

return [
    // other bundles here
    EightPoints\Bundle\GuzzleBundle\EightPointsGuzzleBundle::class => ['all' => true],
];

配置

Guzzle 客户端可以在 config/packages/eight_points_guzzle.yaml 中进行配置。对于使用 Symfony Flex 的项目，此文件将在安装此包时自动创建。对于不使用 Symfony Flex 的项目，此文件应手动创建。

eight_points_guzzle:
    # (de)activate logging/profiler; default: %kernel.debug%
    logging: true

    # configure when a response is considered to be slow (in ms); default 0 (disabled)
    slow_response_time: 1000

    clients:
        payment:
            base_url: 'http://api.payment.example'

            # NOTE: This option marks this Guzzle Client as lazy (https://symfony.ac.cn/doc/master/service_container/lazy_services.html)
            lazy: true # Default `false`

            # guzzle client options (full description here: https://guzzle.readthedocs.org/en/latest/request-options.html)
            options:
                auth:
                    - acme     # login
                    - pa55w0rd # password

                headers:
                    Accept: 'application/json'

                # Find proper php const, for example CURLOPT_SSLVERSION, remove CURLOPT_ and transform to lower case.
                # List of curl options: https://php.ac.cn/manual/en/function.curl-setopt.php
                curl:
                    !php/const:CURL_HTTP_VERSION_1_0: 1

                timeout: 30

            # plugin settings
            plugin: ~

        crm:
            base_url: 'http://api.crm.tld'
            options:
                headers:
                    Accept: 'application/json'

        # More clients here

请参阅 配置参考 了解所有选项的完整列表。

使用

通过此包配置的 Guzzle 客户端在 Symfony 依赖注入容器中可用，名称为 eight_points_guzzle.client.<客户端名称>。例如，配置中名为 payment 的客户端可用作 eight_points_guzzle.client.payment。

假设您有一个需要 Guzzle 客户端的以下控制器

<?php

namespace App\Controller;

use Guzzle\Client;

class ExampleController
{
    public function __construct(Client $client)
    {
        $this->client = $client;
    }
}

使用手动连接，此控制器可以连接如下

services:
    my.example.controller:
        class: App\Controller\ExampleController
        arguments: ['@eight_points_guzzle.client.payment']

对于使用 autowiring 的项目，请参阅 我们的自动连接文档。

插件

此包允许注册和集成插件以扩展 guzzle 和此包的功能。

安装

为了安装插件，请在 src/Kernel.php 中找到以下行：

foreach ($contents as $class => $envs) {
    if ($envs[$this->environment] ?? $envs['all'] ?? false) {
        yield new $class();
    }
}

并用以下内容替换它们：

foreach ($contents as $class => $envs) {
    if ($envs[$this->environment] ?? $envs['all'] ?? false) {
        if ($class === \EightPoints\Bundle\GuzzleBundle\EightPointsGuzzleBundle::class) {
            yield new $class([
                new \Gregurco\Bundle\GuzzleBundleOAuth2Plugin\GuzzleBundleOAuth2Plugin(),
            ]);
        } else {
            yield new $class();
        }
    }
}

已知和支持的插件

• gregurco/GuzzleBundleWssePlugin
• gregurco/GuzzleBundleCachePlugin
• gregurco/GuzzleBundleOAuth2Plugin
• neirda24/GuzzleBundleHeaderForwardPlugin
• neirda24/GuzzleBundleHeaderDisableCachePlugin
• EugenGanshorn/GuzzleBundleRetryPlugin

事件

此包在客户端发出调用之前和之后立即调度 Symfony 事件。每次都会调度两种类型的事件；一种通用事件，无论哪个客户端执行请求都会调度，以及一种客户端特定事件，只调度给特定客户端的特定监听器。这些事件可用于拦截对远程系统的请求以及远程系统的响应。如果通用事件监听器和客户端特定事件监听器都更改了请求/响应，则在发生冲突（例如同时设置相同的标头）的情况下，客户端特定监听器的更改将覆盖通用监听器的更改。

监听事件

要监听这些事件，您应创建一个监听器，并像往常一样将其注册到 Symfony 服务配置中。

services:
    my_guzzle_listener:
        class: App\Service\MyGuzzleBundleListener
        tags:
            # Listen for generic pre transaction event (will receive events for all clients)
            - { name: 'kernel.event_listener', event: 'eight_points_guzzle.pre_transaction', method: 'onPreTransaction' }
            # Listen for client specific pre transaction events (will only receive events for the "payment" client)
            - { name: 'kernel.event_listener', event: 'eight_points_guzzle.pre_transaction.payment', method: 'onPrePaymentTransaction' }

            - # Listen for generic post transaction event (will receive events for all clients)
            - { name: 'kernel.event_listener', event: 'eight_points_guzzle.post_transaction', method: 'onPostTransaction' }
            # Listen for client specific post transaction events (will only receive events for the "payment" client)
            - { name: 'kernel.event_listener', event: 'eight_points_guzzle.post_transaction.payment', method: 'onPostPaymentTransaction' }

有关更多信息，请参阅有关拦截请求和响应的文档。

特性

Symfony 调试工具栏/分析器

日志记录

所有请求都记录到 Symfony 的默认日志记录器（@logger 服务），格式如下（默认格式）：

[{datetime}] eight_points_guzzle.{log_level}: {method} {uri} {code}

示例

[2017-12-01 00:00:00] eight_points_guzzle.INFO: GET http://api.domain.tld 200

您可以通过覆盖 eight_points_guzzle.symfony_log_formatter.pattern 参数来更改消息格式。有关所有选项，请参阅Guzzle 的 MessageFormatter。

建议

为客户端创建别名

如果您的项目使用手动连接，建议为此包创建的客户端创建别名，以获得更容易的服务名称，并使将来更容易切换到其他实现（如果需要的话）。

services:
   crm.client: '@eight_points_guzzle.client.crm'

如果您的项目使用自动连接，此建议不适用。

贡献

👍 如果您想为此包做出贡献，请阅读CONTRIBUTING.md。

加入我们的 Slack 频道 Symfony Devs 进行讨论、提问等： #8p-guzzlebundle。

🎉 感谢所有 贡献者 参与此项目。

了解更多信息

• 自动连接客户端
• 配置参考
• 禁用在 HTTP 错误（4xx 和 5xx 响应）上抛出异常
• 环境变量集成
• 如何创建单文件插件
• 如何重新定义客户端使用的类
• 拦截请求和响应

许可

此包在MIT 许可证下发布。