README

The GuzzleHttpBundle provide Guzzle clients as Symfony services.

安装

使用 Composer 安装扩展包

$ composer require m6web/guzzle-http-bundle

对于旧版本的 Symfony，您可以尝试安装此扩展包的旧版本。

如果您不使用 Symfony Flex，请在您的内核中注册扩展包

return [
    // ...
    M6Web\Bundle\GuzzleHttpBundle\M6WebGuzzleHttpBundle => ['all' => true],
]

使用

在配置文件中添加 m6web_guzzlehttp 部分。以下是所需的最低配置。

# app/config/config.yml
m6web_guzzlehttp:
    clients:
        default: ~
        other:
            base_uri: "http://domain.tld/"

所有在 clients 下的子键定义了一个 Guzzle HTTP 客户端实例。这些服务的名称为 m6web_guzzlehttp_+子键，除了默认子键定义了主要服务 m6web_guzzlehttp。

然后您可以请求容器中的客户端

// in a controller

$client = $this->get('m6web_guzzlehttp'); // default client

try {
    $response = $client->get('http://domain.tld/path/to/resource');

    $promises = [
        'first' => $client->getAsync('http://domain.tld/path/to/resource'),
        'second' => $client->getAsync('http://domain.tld/path/to/other/resource')
    ];

    $result = \GuzzleHttp\Promise\Utils::unwrap($promises);
} catch(\GuzzleHttp\Exception\ConnectException $e) {
    // connection problem like timeout
}

// use other client
$otherClient = $this->get('m6web_guzzlehttp_other');
$response = $otherClient->get('path/to/resource'); // call http://domain.tld/path/to/resource

该服务返回一个配置好的 Guzzle 客户端，有关如何使用它的更多信息，您可以阅读 guzzle6 文档。

与 Guzzle6 的唯一区别在于使用 curl 处理重定向响应。您可以选择通过将配置键 redirect_handler 设置为 guzzle 来使用 Guzzle 的重定向行为。

当有缓存系统可用时，您可以在 Guzzle 选项中添加 cache_force 和 cache_ttl，分别用于在请求之前强制清除缓存和使用特定的 ttl 覆盖配置。

$client = $this->get('m6web_guzzlehttp');

$response = $client->get('http://domain.tld', ['cache_force' => true]); // remove cache entry and set a new one

$response = $client->get('http://doamin.tld/path', ['cache_ttl' => 200]); // set ttl to 200 seconds instead the default one

数据收集器

当启用 Symfony 分析器时，可用的数据收集器。

它允许您检查以下数据

方法
URL
响应代码和原因
执行时间
重定向次数
重定向时间
缓存命中
缓存 TTL

注意：如果您选择 Guzzle 作为 redirect_handler，则重定向次数和重定向时间始终为零。当设置缓存系统时，可用缓存信息。

缓存系统

您可以通过在配置中添加 guzzlehttp_cache 并将 service 子键设置为引用实现 M6Web\Bundle\GuzzleHttpBundle\Cache\CacheInterface 的服务来为请求设置缓存。

# app/config/config.yml
m6web_guzzlehttp:
    clients:
        default:
            base_uri: "http://domain.tld/"
            guzzlehttp_cache:
                service: my_cache_service

我们提供了一个“内存”缓存类，您可以通过定义一个新的缓存服务并在 Guzzle 配置中使用它来使用。

# app/config/config.yml
services:
    company.guzzle.cache.inmemory:
        class: M6Web\Bundle\GuzzleHttpBundle\Cache\InMemory

m6web_guzzlehttp:
    clients:
        default:
            guzzlehttp_cache:
                service: company.guzzle.cache.inmemory

我们还通过我们的 RedisBundle >= 2.4 提供了 Redis 缓存接口，您可以使用以下方式使用

# app/config/config.yml
m6web_guzzlehttp:
    clients:
        default:
            base_uri: "http://domain.tld/"
            guzzlehttp_cache:
                service: m6_redis.guzzlehttp

m6_redis:
    servers:
        default:
            ip:   '127.0.0.1'
            port: 6379
    clients:
        guzzlehttp:
            servers:   ["default"]     # list of servers to use
            namespace: GuzzleHttp\
            timeout:   2               # timeout in second
            readwritetimeout: 2        # read-write timeout in second
            class: M6Web\Bundle\RedisBundle\CacheAdapters\M6WebGuzzleHttp

有关如何设置 RedisBundle 的更多信息，请参阅项目中的 README。

我们还通过 ApcuBundle 提供了相同的缓存系统。

配置参考

由于一些配置选项接受多种数据类型，所有服务引用都必须以 @ 字符开始。

m6web_guzzlehttp:
    clients_share_the_same_handler: false          # Use "true" if you want all your clients to share the same Guzzle handler. It means that your different clients will be able to send asynchronous requests altogether.
    clients:
        default:
            base_uri: ""                           # Base uri to prepend on request uri
            timeout: 5.0                           # request timeout
            http_errors: true                      # Use "false" to disable throwing exceptions on HTTP protocol errors
            redirect_handler: curl                 # guzzle or curl
            guzzlehttp_cache:                      # optional cache
                cache_server_errors: true          # at false, no server errors will be cached
                cache_client_errors: true          # at false, no client errors will be cached
                default_ttl: 3600                  # default ttl for cache entry in seconds
                ignore_cache_errors: false         # if true, no exception would be thrown when cache is unavailable
                use_header_ttl: false              # use the cache-control header to set the ttl
                service: '@my_cache_service'       # reference to service who implements the cache interface
            headers:                               # optional. Default request headers
                User_Agent: "m6web/1.0"            # set header "User-Agent" with the value "m6web/1.0"
                header\_name: "my value"           # set header "header_name" with value "my value"
            auth: ["user", "password"]             # optional, http auth user and password
            allow_redirects:                       # false to disallow redirection or an array describing the redirect behavior of a request
                max: 5                             # Maximum redirect to follow
                strict: false                      # use "strict" RFC compliant redirects. (guzzle redirect handler only)
                referer: true                      # add a Referer header
                protocols: ['http', 'https']       # restrict redirect to a protocol
            body: '@my.body.service'               # string | service reference, request body
            cert: ['/path/to/.pem', 'password']    # string | array, Set to a string to specify client side certificate, an array if a password is required
            cookies:                               # boolean | array, false disable cookies
                -
                    name: "bar"
                    value: "foo"
                    domain: "foobar.com"
                    path: "/my/path"
                    max: 100
                    expires: null
                    secure: false
                    discard: false
                    httpOnly: false
                    max-age: null
                -
                    name: tracker
                    value: tracker
            connect_timeout: 1                     # float, Float describing the number of seconds to wait while trying to connect to a server
            debug: true                            # boolean, Set to true to enable debug output with the handler used to send a request
            decode_content: true                   # string | boolean, specify whether Content-Encoding responses are automatically decoded
            delay: 10                              # boolean | float, the number of milliseconds to delay before sending the request
            expect: true                           # boolean | integer, controls the behavior of the "Expect: 100-Continue" header
            force_ip_resolve:                      # Set to "v4" if you want the HTTP handlers to use only ipv4 protocol or "v6" for ipv6 protocol.
            form_params:                           # array, Used to send an application/x-www-form-urlencoded POST request.
                foo: 'bar'
                bar: 'foo'
            json: [ foo: 'bar' ]                   # mixed, the json option is used to easily upload JSON encoded data as the body of a request
            multipart:                             # array, Sets the body of the request to a multipart/form-data form.
                -
                    name: 'foo'
                    contents: 'bar'
                    headers:
                        X-foo: 'bar'
                        X-bar: 'foo'
            on_headers: '@invokable.service.id'    # A callable that is invoked when the HTTP headers of the response have been received
            on_stats: '@invokable.service.id'      # on_stats allows you to get access to transfer statistics
            proxy:                                 # string | array, Pass a string to specify an HTTP proxy, or an array to specify different proxies for different protocols.
                http: 'tcp://localhost:8125'
            query:                                 # array, Associative array of query string values or query string to add to the request.
                foo: 'bar'
                bar: 'foo'
            sink: '/path/to/file'                  # String or Psr\Http\Message\StreamInterface service, Specify where the body of a response will be saved.
            ssl_key: ['/path/to/.pem', 'password'] # string | array, Specify the path to a file containing a private SSL key in PEM format.
            stream: true                           # Boolean, Set to true to stream a response rather than download it all up-front.
            synchronous: true                      # Boolean, Set to true to inform HTTP handlers that you intend on waiting on the response. This can be useful for optimizations.
            verify: true                           # Boolean Describes the SSL certificate verification behavior of a request.
            version: 1.0                           # String Protocol version to use with the request.

        otherclient:
            ...

对于 headers 选项，数组中的键代表头部名称。下划线将被转换为连字符，除非它被反斜杠转义。

添加中间件

实现 M6Web\Bundle\GuzzleHttpBundle\Middleware\MiddlewareInterface。

使用 m6web_guzzlehttp.middleware 标记您的服务，并指定客户端如下

Acme\Infra\GraphQL\Client\MyMiddleware:
        tags:
            - {name: 'm6web_guzzlehttp.middleware', client: 'myclient' }

贡献

首先，感谢您的贡献！

以下是一些规则，以便在维护者接受并合并您的 pull request 之前更容易地进行代码审查

您必须编写或更新测试
您必须编写或更新文档
CI 必须通过您的 pull request

运行测试

安装 composer 的开发依赖项

make install

然后使用atoum 单元测试框架运行测试

make test

m6web / guzzle-http-bundle

维护者

详细信息