README

要求 | 安装 | 使用 | 贡献 | 安全 | 许可 | 关于

GuzzleBundle

Mapudo GuzzleBundle 允许将 Guzzle 集成到 Symfony 项目中。

此包的主要特性包括

• 轻松添加自定义中间件和事件监听器
• 接近 100% 的测试覆盖率
• 从底层开始为 PHP 7 编写
• 内置中间件
  • 通过 Monolog 在单独的 guzzle 通道上进行日志记录
  • 通过 Symfony Profiler (使用 Bootstrap 风格化) 和 DebugBar 进行请求调试
  • 通过 Symfony 事件框架进行事件分发

为什么还需要另一个 Guzzle Bundle？我们只是对现有包的代码质量和中间件集成不满意，而且他们的维护者没有解决我们的问题。

要求

• PHP 7.0 及更高版本
• Symfony ~2.8|~3.0|~4.0

安装

通过 Composer

$ composer require mapudo/guzzle-bundle

使用

激活包

在您的 AppKernel.php 中注册包。

// app/AppKernel.php
...
new Mapudo\Bundle\GuzzleBundle\GuzzleBundle(), 
...

配置

通过 app/config.yml 配置包。您可以为多个客户端定义基本选项。

guzzle:
    clients:
        test_client:
            base_uri: 'https://example.com/path'
            headers:
                Accept: 'application/json'
                Accept-Language: 'de'
            request_options:
                allow_redirects: true
                cert:
                    - '/path/to/cert.pem'
                    - 'password'
        another_client:
            base_uri: 'https://another.example.com/root/child'
            headers:
                X-Auth: 'token'

所有在 Guzzle 文档 中文档化的 request_options 都可以配置给客户端，但以下选项只能为单个请求设置

• body
• cookies
• debug
• form_params
• json
• multipart
• on_headers
• on_stats
• progress
• sink

配置中定义的客户端随后将由包的 CompilerPass 注册，然后您可以通过名称从容器中访问它们。对于上述情况，我们将有两个客户端，我们可以使用 guzzle.client.test_client 和 guzzle.client.another_client 访问它们。

发出请求

发出请求很容易，本质上与直接使用 Guzzle 相同。如上所述，您也可以在此处设置通过配置不可用的 request_options。

<?php
$client = $container->get('guzzle.client.test_client');
$moreOptions = ['on_stats' => function (\GuzzleHttp\TransferStats $stats) {
    echo $stats->getEffectiveUri() . "\n";
    echo $stats->getTransferTime() . "\n";
}];
$client->requestAsync(\Symfony\Component\HttpFoundation\Request::METHOD_GET, '/path/without/base_uri', $moreOptions);

注意： 在添加新的日志处理器或中间件后，请清除缓存，以便再次运行 CompilerPass。

日志记录

CompilerPass 注册了一个日志中间件，它定义了一个 guzzle 日志通道。默认情况下，所有在您的配置中定义的 Monolog 处理程序都将记录这些请求。要禁用特定处理程序的日志记录，请将 !guzzle 添加到处理程序的通道列表中。

monolog:
   handlers:
       main:
           channels: [!guzzle]

还可以将请求数据记录到 Symfony Profiler 和调试工具栏中。要执行此操作，请使用以下配置激活内置的 profiler 处理程序

monolog:
    handlers:
        my_debug_handler:
            type: service
            id: mapudo_bundle_guzzle.log_handler.symfony_profiler_handler
            level: debug
            channels: [guzzle]
        ## add additional handlers as needed
        # my_other_handler:
            # ...
            # channels: [guzzle]

添加此处理程序后，您需要重新构建资产，以便您的Profiler能够以正确样式显示，例如使用assets:install。在这里，您可以选择显示哪个客户端的请求。

登录特定通道

默认情况下，LogMiddleware将日志记录到“guzzle”通道。如果您想使用不同的处理程序（取决于通道），您可以为此定义一个服务标签。

YAML

mapudo_frontend.mapudo_api.log_middleware:
    class: Mapudo\Bundle\GuzzleBundle\Middleware\LogMiddleware
    tags:
        - { name: guzzle.middleware, method: log, client: mapudo_api, channel: timings }

如你所见，现在标签包含一个“channel”节点。如果配置如此，guzzle客户端mapudo_api将注入使用/多个日志记录到计时通道的LogMiddleware作为中间件。

重要

请注意，LogMiddleware的服务ID必须包含名称log_middleware，因为编译器传递会检查服务定义是否包含此名称以检索通道。

添加自己的日志记录

此包使用Symfony的规范化器在将请求和响应对象传递给日志记录器之前规范化它们。这允许您将请求和响应作为数组处理。如果您想用对象来处理，该包提供请求和响应规范化器，它将数组转换为相应的对象。

例如，要编写自己的处理程序，请从给定上下文中取出响应和请求数组，并对其进行规范化。

<?php
if ($record['context']) {
    $response = null;
    if (!empty($record['context']['response'])) {
        $response = $this->responseDenormalizer->denormalize($record['context']['response'], Response::class);
    }
    if (!empty($record['context']['request'])) {
        /** @var Request $request */
        $request = $this->requestDenormalizer->denormalize($record['context']['request'], Request::class);
        $request->setResponse($response);
    }
}

或者只做你想做的。

中间件

此包已经实现了两个中间件服务。一个是派发事件，另一个是使用给定处理程序的日志记录。

添加自己的中间件

该包支持使用__invoke()或创建自定义method来注册中间件。

编译器传递会搜索带有guzzle.middleware标签的服务。标签method是可选的，用于定义如果没有在中间件中使用__invoke()，则应执行哪个方法。您需要添加带有客户端名称的client标签。然而，如果您想为所有客户端创建中间件，则可以省略此标签。

YAML

services:
    guzzle.middleware.my_middleware:
        class: exampleClass
        tags:
            - { name: guzzle.middleware, method: addMyMiddleware, client: test_client }

XML

<services>
    <service id="guzzle.middleware.my_middleware" class="exampleClass">
        <tag name="guzzle.middleware" method="addMyMiddleware" client="test_client"/>
    </service>
</services>

事件

添加自己的事件监听器

编译器传递会搜索带有kernel.event_listener标签的服务。标签event也是必需的，用于定义要监听哪个事件。您可以使用guzzle_event.pre_transaction或guzzle_event.post_transaction。与中间件不同，这里需要一个客户端名称。

YAML

services:
    guzzle.event.my_event:
        class: exampleClass
        tags:
            - { name: kernel.event_listener, event: guzzle_event.pre_transaction, client: test_client }

XML

<services>
    <service id="guzzle.event.my_event" class="exampleClass">
        <tag name="kernel.event_listener" event="guzzle_event.pre_transaction" client="test_client"/>
    </service>
</services>

贡献

有关详细信息，请参阅CONTRIBUTING。

安全

如果您发现任何安全相关的问题，请通过电子邮件mailto:security@mapudo.com而不是使用问题跟踪器。

许可

MIT许可（MIT）。有关更多信息，请参阅许可文件。

关于

此包由Mapudo编写，Mapudo是在线物料市场。 我们在招聘！