| Q             | A
| ------------- | ---
| Branch?       | master
| Bug fix?      | no
| New feature?  | yes
| BC breaks?    | no
| Deprecations? | no
| Tests pass?   | yes
| Fixed tickets | -
| License       | MIT
| Doc PR        | -

Sooner that later, we'll need to send HTTP calls to APIs,
e.g. Symfony Mailer or symfony#27738 already need it.

Common existing HTTP clients for PHP rely on PSR-7,
which is orthogonal to the way Symfony is designed.

More reasons we need this in core are the package principles:
if we want to be able to keep our BC+deprecation promises, we
have to build on more stable and more abstract dependencies than
Symfony itself.

So here we are. This PR introduces a new `Http` namespace in contracts,
and a new `HttpClient` component.

Its surface is by design very simple to use, while still flexible
enough to cover more advanced use cases thanks to streaming+laziness.

Two full implementations are provided:
 - `NativeHttpClient` is based on PHP's HTTP stream wrapper. It's the
   most portable one but relies on a blocking `fopen()`.
 - `CurlHttpClient` relies on the curl extension. It supports full
   concurrency and HTTP/2.

Here are some examples that work with both clients.

For common cases, all the methods on reponses are synchronous:
```php
$client = new NativeHttpClient();

$response = $client->get('https://google.com');

$statusCode = $response->getStatusCode();
$headers = $response->getHeaders();
$content = $response->getContent();
```

When several responses need to be fetched concurrently,
clients provide a `complete()` method, e.g.:

```php
$client = new CurlHttpClient();
$pool = [];

for ($i = 0; $i < 379; ++$i) {
    $pool[] = $client->get("https://http2.akamai.com/demo/tile-$i.png");
}

foreach ($client->complete($pool) as $r) {
    $r->getHeaders();
}
```

The `complete()` method accepts a second `$timeout` argument that defaults
to `ini_get('default_socket_timeout')`, typically 60s. The `foreach` will
skip responses that are *inactive* for longer than the timeout.

Providing `0` as timeout allows iterating over already completed responses
in a non-blocking way.

When a next response depends on the result of a previous one, it's also
possible to schedule new responses for completion. Doing so is incompatible
with `foreach` and requires using the `Generator` interface directly,
its `send()` method especially:

```php
$client = new CurlHttpClient();

// [...] populate $pool of responses for some first requests as above

$responses = $client->complete($pool);

while ($responses->valid()) {
    $completedResponse = $responses->current();
    $completedKey = $responses->key(); // the key of the response in $pool

    // [...] compute $moreResponses based e.g. on $completedResponse/Key

    if ($moreResponses) {
        $responses->send($moreResponses);
    } else {
        $responses->next();
    }
}
```

By default, clients follow redirections. When the redirection limit is
reached, or when a `4xx` or a `5xx` happens, an exception is thrown.

An array of options allows adjusting the behavior when sending requests.
They are documented in `HttpClientTrait`.

TODO:
 - [ ] validate the design
 - [ ] add tests
 - [ ] split in several PRs?

Implemented:
 - flexible contracts for HTTP clients
 - fopen()+curl-based clients
 - gzip compression enabled when possible
 - fetch multiple responses concurrently
 - progress function able to cancel the request
 - flexible timeout management

Help wanted (can be done after merge):
 - handle standard proxy-related env vars when using NativeHttpClient
 - logger integration
 - a TraceableHttpClient and integration with the profiler
 - FrameworkBundle integration: autowireable alias + semantic configuration for default options
 - help clarify the contracts where needed
 - implement bridges with existing HTTP clients in contrib packages
 - mock client

Other ideas for the future:
 - HTTP/2 push as a temporary cache in complete()
 - cookie jar as a new "cookie_jar" option
 - a MIME multipart stream builder
 - HTTP cache as a decorating client
 - etc.

| Q             | A
| ------------- | ---
| Branch?       | master
| Bug fix?      | no
| New feature?  | yes
| BC breaks?    | no
| Deprecations? | no
| Tests pass?   | yes
| Fixed tickets | -
| License       | MIT
| Doc PR        | -

Sooner that later, we'll need to send HTTP calls to APIs,
e.g. Symfony Mailer or symfony#27738 already need it.

Common existing HTTP clients for PHP rely on PSR-7,
which is orthogonal to the way Symfony is designed.

More reasons we need this in core are the package principles:
if we want to be able to keep our BC+deprecation promises, we
have to build on more stable and more abstract dependencies than
Symfony itself.

So here we are. This PR introduces a new `Http` namespace in contracts,
and a new `HttpClient` component.

Its surface is by design very simple to use, while still flexible
enough to cover more advanced use cases thanks to streaming+laziness.

Two full implementations are provided:
 - `NativeHttpClient` is based on PHP's HTTP stream wrapper. It's the
   most portable one but relies on a blocking `fopen()`.
 - `CurlHttpClient` relies on the curl extension. It supports full
   concurrency and HTTP/2.

Here are some examples that work with both clients.

For common cases, all the methods on reponses are synchronous:
```php
$client = new NativeHttpClient();

$response = $client->get('https://google.com');

$statusCode = $response->getStatusCode();
$headers = $response->getHeaders();
$content = $response->getContent();
```

When several responses need to be fetched concurrently,
clients provide a `complete()` method, e.g.:

```php
$client = new CurlHttpClient();
$pool = [];

for ($i = 0; $i < 379; ++$i) {
    $pool[] = $client->get("https://http2.akamai.com/demo/tile-$i.png");
}

foreach ($client->complete($pool) as $r) {
    $r->getHeaders();
}
```

The `complete()` method accepts a second `$timeout` argument that defaults
to `ini_get('default_socket_timeout')`, typically 60s. The `foreach` will
skip responses that are *inactive* for longer than the timeout.

Providing `0` as timeout allows iterating over already completed responses
in a non-blocking way.

When a next response depends on the result of a previous one, it's also
possible to schedule new responses for completion. Doing so is incompatible
with `foreach` and requires using the `Generator` interface directly,
its `send()` method especially:

```php
$client = new CurlHttpClient();

// [...] populate $pool of responses for some first requests as above

$responses = $client->complete($pool);

while ($responses->valid()) {
    $completedResponse = $responses->current();
    $completedKey = $responses->key(); // the key of the response in $pool

    // [...] compute $moreResponses based e.g. on $completedResponse/Key

    if ($moreResponses) {
        $responses->send($moreResponses);
    } else {
        $responses->next();
    }
}
```

By default, clients follow redirections. When the redirection limit is
reached, or when a `4xx` or a `5xx` happens, an exception is thrown.

An array of options allows adjusting the behavior when sending requests.
They are documented in `HttpClientTrait`.

TODO:
 - [ ] validate the design
 - [ ] add tests
 - [ ] split in several PRs?

Implemented:
 - flexible contracts for HTTP clients
 - fopen()+curl-based clients
 - gzip compression enabled when possible
 - fetch multiple responses concurrently
 - progress function able to cancel the request
 - flexible timeout management

Help wanted (can be done after merge):
 - handle standard proxy-related env vars when using NativeHttpClient
 - logger integration
 - a TraceableHttpClient and integration with the profiler
 - FrameworkBundle integration: autowireable alias + semantic configuration for default options
 - help clarify the contracts where needed
 - implement bridges with existing HTTP clients in contrib packages
 - mock client

Other ideas for the future:
 - HTTP/2 push as a temporary cache in complete()
 - cookie jar as a new "cookie_jar" option
 - a MIME multipart stream builder
 - HTTP cache as a decorating client
 - etc.

| Q             | A
| ------------- | ---
| Branch?       | master
| Bug fix?      | no
| New feature?  | yes
| BC breaks?    | no
| Deprecations? | no
| Tests pass?   | yes
| Fixed tickets | -
| License       | MIT
| Doc PR        | -

Sooner that later, we'll need to send HTTP calls to APIs,
e.g. Symfony Mailer or symfony#27738 already need it.

Common existing HTTP clients for PHP rely on PSR-7,
which is orthogonal to the way Symfony is designed.

More reasons we need this in core are the package principles:
if we want to be able to keep our BC+deprecation promises, we
have to build on more stable and more abstract dependencies than
Symfony itself.

So here we are. This PR introduces a new `Http` namespace in contracts,
and a new `HttpClient` component.

Its surface is by design very simple to use, while still flexible
enough to cover more advanced use cases thanks to streaming+laziness.

Two full implementations are provided:
 - `NativeHttpClient` is based on PHP's HTTP stream wrapper. It's the
   most portable one but relies on a blocking `fopen()`.
 - `CurlHttpClient` relies on the curl extension. It supports full
   concurrency and HTTP/2.

Here are some examples that work with both clients.

For common cases, all the methods on reponses are synchronous:
```php
$client = new NativeHttpClient();

$response = $client->get('https://google.com');

$statusCode = $response->getStatusCode();
$headers = $response->getHeaders();
$content = $response->getContent();
```

When several responses need to be fetched concurrently,
clients provide a `complete()` method, e.g.:

```php
$client = new CurlHttpClient();
$pool = [];

for ($i = 0; $i < 379; ++$i) {
    $pool[] = $client->get("https://http2.akamai.com/demo/tile-$i.png");
}

foreach ($client->complete($pool) as $r) {
    $r->getHeaders();
}
```

The `complete()` method accepts a second `$timeout` argument that defaults
to `ini_get('default_socket_timeout')`, typically 60s. The `foreach` will
skip responses that are *inactive* for longer than the timeout.

Providing `0` as timeout allows iterating over already completed responses
in a non-blocking way.

When a next response depends on the result of a previous one, it's also
possible to schedule new responses for completion. Doing so is incompatible
with `foreach` and requires using the `Generator` interface directly,
its `send()` method especially:

```php
$client = new CurlHttpClient();

// [...] populate $pool of responses for some first requests as above

$responses = $client->complete($pool);

while ($responses->valid()) {
    $completedResponse = $responses->current();
    $completedKey = $responses->key(); // the key of the response in $pool

    // [...] compute $moreResponses based e.g. on $completedResponse/Key

    if ($moreResponses) {
        $responses->send($moreResponses);
    } else {
        $responses->next();
    }
}
```

By default, clients follow redirections. When the redirection limit is
reached, or when a `4xx` or a `5xx` happens, an exception is thrown.

An array of options allows adjusting the behavior when sending requests.
They are documented in `HttpClientTrait`.

TODO:
 - [ ] validate the design
 - [ ] add tests
 - [ ] split in several PRs?

Implemented:
 - flexible contracts for HTTP clients
 - fopen()+curl-based clients
 - gzip compression enabled when possible
 - fetch multiple responses concurrently
 - progress function able to cancel the request
 - flexible timeout management

Help wanted (can be done after merge):
 - handle standard proxy-related env vars when using NativeHttpClient
 - logger integration
 - a TraceableHttpClient and integration with the profiler
 - FrameworkBundle integration: autowireable alias + semantic configuration for default options
 - help clarify the contracts where needed
 - implement bridges with existing HTTP clients in contrib packages
 - mock client

Other ideas for the future:
 - HTTP/2 push as a temporary cache in complete()
 - cookie jar as a new "cookie_jar" option
 - a MIME multipart stream builder
 - HTTP cache as a decorating client
 - etc.

| Q             | A
| ------------- | ---
| Branch?       | master
| Bug fix?      | no
| New feature?  | yes
| BC breaks?    | no
| Deprecations? | no
| Tests pass?   | yes
| Fixed tickets | -
| License       | MIT
| Doc PR        | -

Sooner that later, we'll need to send HTTP calls to APIs,
e.g. Symfony Mailer or symfony#27738 already need it.

Common existing HTTP clients for PHP rely on PSR-7,
which is orthogonal to the way Symfony is designed.

More reasons we need this in core are the package principles:
if we want to be able to keep our BC+deprecation promises, we
have to build on more stable and more abstract dependencies than
Symfony itself.

So here we are. This PR introduces a new `Http` namespace in contracts,
and a new `HttpClient` component.

Its surface is by design very simple to use, while still flexible
enough to cover more advanced use cases thanks to streaming+laziness.

Two full implementations are provided:
 - `NativeHttpClient` is based on PHP's HTTP stream wrapper. It's the
   most portable one but relies on a blocking `fopen()`.
 - `CurlHttpClient` relies on the curl extension. It supports full
   concurrency and HTTP/2.

Here are some examples that work with both clients.

For common cases, all the methods on reponses are synchronous:
```php
$client = new NativeHttpClient();

$response = $client->get('https://google.com');

$statusCode = $response->getStatusCode();
$headers = $response->getHeaders();
$content = $response->getContent();
```

When several responses need to be fetched concurrently,
clients provide a `complete()` method, e.g.:

```php
$client = new CurlHttpClient();
$pool = [];

for ($i = 0; $i < 379; ++$i) {
    $pool[] = $client->get("https://http2.akamai.com/demo/tile-$i.png");
}

foreach ($client->complete($pool) as $r) {
    $r->getHeaders();
}
```

The `complete()` method accepts a second `$timeout` argument that defaults
to `ini_get('default_socket_timeout')`, typically 60s. The `foreach` will
skip responses that are *inactive* for longer than the timeout. These
inactive responses are available by calling `$responses->getReturn()`
after iterating is done.

Providing `0` as timeout allows iterating over already completed responses
in a non-blocking way.

When a next response depends on the result of a previous one, it's also
possible to schedule new responses for completion. Doing so is incompatible
with `foreach` and requires using the `Generator` interface directly,
its `send()` method especially:

```php
$client = new CurlHttpClient();

// [...] populate $pool of responses for some first requests as above

$responses = $client->complete($pool);

while ($responses->valid()) {
    $completedResponse = $responses->current();
    $completedKey = $responses->key(); // the key of the response in $pool

    // [...] compute $moreResponses based e.g. on $completedResponse/Key

    if ($moreResponses) {
        $responses->send($moreResponses);
    } else {
        $responses->next();
    }
}
```

By default, clients follow redirections. When the redirection limit is
reached, or when a `4xx` or a `5xx` happens, an exception is thrown.

An array of options allows adjusting the behavior when sending requests.
They are documented in `HttpClientTrait`.

TODO:
 - [ ] validate the design
 - [ ] add tests
 - [ ] split in several PRs?

Implemented:
 - flexible contracts for HTTP clients
 - `fopen()`+`curl`-based clients
 - gzip compression enabled when possible
 - fetch multiple responses concurrently
 - progress function able to cancel the request
 - flexible timeout management

Help wanted (can be done after merge):
 - handle standard proxy-related env vars when using `NativeHttpClient`
 - logger integration
 - `TraceableHttpClient` and integration with the profiler
 - `FrameworkBundle` integration: autowireable alias + semantic configuration for default options
 - help clarify the contracts where needed
 - implement bridges with existing HTTP clients in contrib packages
 - mock client

More ideas:
 - HTTP/2 push as a temporary cache in `complete()`
 - cookie jar with a new `"cookie_jar"` option
 - a MIME multipart stream builder
 - make `NativeResponse::getAttribute()` return attributes inspired from `curl_getinfo()`
 - etc.

| Q             | A
| ------------- | ---
| Branch?       | master
| Bug fix?      | no
| New feature?  | yes
| BC breaks?    | no
| Deprecations? | no
| Tests pass?   | yes
| Fixed tickets | -
| License       | MIT
| Doc PR        | -

Sooner that later, we'll need to send HTTP calls to APIs,
e.g. Symfony Mailer or symfony#27738 already need it.

Common existing HTTP clients for PHP rely on PSR-7,
which is orthogonal to the way Symfony is designed.

More reasons we need this in core are the package principles:
if we want to be able to keep our BC+deprecation promises, we
have to build on more stable and more abstract dependencies than
Symfony itself.

So here we are. This PR introduces a new `Http` namespace in contracts,
and a new `HttpClient` component.

Its surface is by design very simple to use, while still flexible
enough to cover more advanced use cases thanks to streaming+laziness.

Two full implementations are provided:
 - `NativeHttpClient` is based on PHP's HTTP stream wrapper. It's the
   most portable one but relies on a blocking `fopen()`.
 - `CurlHttpClient` relies on the curl extension. It supports full
   concurrency and HTTP/2.

Here are some examples that work with both clients.

For common cases, all the methods on reponses are synchronous:
```php
$client = new NativeHttpClient();

$response = $client->get('https://google.com');

$statusCode = $response->getStatusCode();
$headers = $response->getHeaders();
$content = $response->getContent();
```

When several responses need to be fetched concurrently,
clients provide a `complete()` method, e.g.:

```php
$client = new CurlHttpClient();
$pool = [];

for ($i = 0; $i < 379; ++$i) {
    $pool[] = $client->get("https://http2.akamai.com/demo/tile-$i.png");
}

foreach ($client->complete($pool) as $r) {
    $r->getHeaders();
}
```

The `complete()` method accepts a second `$timeout` argument that defaults
to `ini_get('default_socket_timeout')`, typically 60s. The `foreach` will
skip responses that are *inactive* for longer than the timeout. These
inactive responses are available by calling `$responses->getReturn()`
after iterating is done.

Providing `0` as timeout allows iterating over already completed responses
in a non-blocking way.

When a next response depends on the result of a previous one, it's also
possible to schedule new responses for completion. Doing so is incompatible
with `foreach` and requires using the `Generator` interface directly,
its `send()` method especially:

```php
$client = new CurlHttpClient();

// [...] populate $pool of responses for some first requests as above

$responses = $client->complete($pool);

while ($responses->valid()) {
    $completedResponse = $responses->current();
    $completedKey = $responses->key(); // the key of the response in $pool

    // [...] compute $moreResponses based e.g. on $completedResponse/Key

    if ($moreResponses) {
        $responses->send($moreResponses);
    } else {
        $responses->next();
    }
}
```

By default, clients follow redirections. When the redirection limit is
reached, or when a `4xx` or a `5xx` happens, an exception is thrown.

An array of options allows adjusting the behavior when sending requests.
They are documented in `HttpClientTrait`.

TODO:
 - [ ] validate the design
 - [ ] add tests
 - [ ] split in several PRs?

Implemented:
 - flexible contracts for HTTP clients
 - `fopen()`+`curl`-based clients
 - gzip compression enabled when possible
 - fetch multiple responses concurrently
 - progress function able to cancel the request
 - flexible timeout management

Help wanted (can be done after merge):
 - handle standard proxy-related env vars when using `NativeHttpClient`
 - logger integration
 - `TraceableHttpClient` and integration with the profiler
 - `FrameworkBundle` integration: autowireable alias + semantic configuration for default options
 - help clarify the contracts where needed
 - implement bridges with existing HTTP clients in contrib packages
 - mock client

More ideas:
 - HTTP/2 push as a temporary cache in `complete()`
 - cookie jar with a new `"cookie_jar"` option
 - a MIME multipart stream builder
 - make `NativeResponse::getAttribute()` return attributes inspired from `curl_getinfo()`
 - etc.

| Q             | A
| ------------- | ---
| Branch?       | master
| Bug fix?      | no
| New feature?  | yes
| BC breaks?    | no
| Deprecations? | no
| Tests pass?   | yes
| Fixed tickets | -
| License       | MIT
| Doc PR        | -

Sooner that later, we'll need to send HTTP calls to APIs,
e.g. Symfony Mailer or symfony#27738 already need it.

Common existing HTTP clients for PHP rely on PSR-7,
which is orthogonal to the way Symfony is designed.

More reasons we need this in core are the package principles:
if we want to be able to keep our BC+deprecation promises, we
have to build on more stable and more abstract dependencies than
Symfony itself.

So here we are. This PR introduces a new `Http` namespace in contracts,
and a new `HttpClient` component.

Its surface is by design very simple to use, while still flexible
enough to cover more advanced use cases thanks to streaming+laziness.

Two full implementations are provided:
 - `NativeHttpClient` is based on PHP's HTTP stream wrapper. It's the
   most portable one but relies on a blocking `fopen()`.
 - `CurlHttpClient` relies on the curl extension. It supports full
   concurrency and HTTP/2.

Here are some examples that work with both clients.

For common cases, all the methods on reponses are synchronous:
```php
$client = new NativeHttpClient();

$response = $client->get('https://google.com');

$statusCode = $response->getStatusCode();
$headers = $response->getHeaders();
$content = $response->getContent();
```

When several responses need to be fetched concurrently,
clients provide a `complete()` method, e.g.:

```php
$client = new CurlHttpClient();
$pool = [];

for ($i = 0; $i < 379; ++$i) {
    $pool[] = $client->get("https://http2.akamai.com/demo/tile-$i.png");
}

foreach ($client->complete($pool) as $r) {
    $r->getHeaders();
}
```

The `complete()` method accepts a second `$timeout` argument that defaults
to `ini_get('default_socket_timeout')`, typically 60s. The `foreach` will
skip responses that are *inactive* for longer than the timeout. These
inactive responses are available by calling `$responses->getReturn()`
after iterating is done.

Providing `0` as timeout allows iterating over already completed responses
in a non-blocking way.

When a next response depends on the result of a previous one, it's also
possible to schedule new responses for completion. Doing so is incompatible
with `foreach` and requires using the `Generator` interface directly,
its `send()` method especially:

```php
$client = new CurlHttpClient();

// [...] populate $pool of responses for some first requests as above

$responses = $client->complete($pool);

while ($responses->valid()) {
    $completedResponse = $responses->current();
    $completedKey = $responses->key(); // the key of the response in $pool

    // [...] compute $moreResponses based e.g. on $completedResponse/Key

    if ($moreResponses) {
        $responses->send($moreResponses);
    } else {
        $responses->next();
    }
}
```

By default, clients follow redirections. When the redirection limit is
reached, or when a `4xx` or a `5xx` happens, an exception is thrown.

An array of options allows adjusting the behavior when sending requests.
They are documented in `HttpClientTrait`.

TODO:
 - [ ] validate the design
 - [ ] add tests
 - [ ] split in several PRs?

Implemented:
 - flexible contracts for HTTP clients
 - `fopen()`+`curl`-based clients
 - gzip compression enabled when possible
 - fetch multiple responses concurrently
 - progress function able to cancel the request
 - flexible timeout management
 - public key pinning

Help wanted (can be done after merge):
 - handle standard proxy-related env vars when using `NativeHttpClient`
 - logger integration
 - `TraceableHttpClient` and integration with the profiler
 - `FrameworkBundle` integration: autowireable alias + semantic configuration for default options
 - help clarify the contracts where needed
 - implement bridges with existing HTTP clients in contrib packages
 - mock client

More ideas:
 - HTTP/2 push as a temporary cache in `complete()`
 - cookie jar with a new `"cookie_jar"` option
 - a MIME multipart stream builder
 - make `NativeResponse::getAttribute()` return attributes inspired from `curl_getinfo()`
 - HTTP/HSTS cache
 - etc.

| Q             | A
| ------------- | ---
| Branch?       | master
| Bug fix?      | no
| New feature?  | yes
| BC breaks?    | no
| Deprecations? | no
| Tests pass?   | yes
| Fixed tickets | -
| License       | MIT
| Doc PR        | -

Sooner that later, we'll need to send HTTP calls to APIs,
e.g. Symfony Mailer or symfony#27738 already need it.

Common existing HTTP clients for PHP rely on PSR-7,
which is orthogonal to the way Symfony is designed.

More reasons we need this in core are the package principles:
if we want to be able to keep our BC+deprecation promises, we
have to build on more stable and more abstract dependencies than
Symfony itself.

So here we are. This PR introduces a new `Http` namespace in contracts,
and a new `HttpClient` component.

Its surface is by design very simple to use, while still flexible
enough to cover more advanced use cases thanks to streaming+laziness.

Two full implementations are provided:
 - `NativeHttpClient` is based on PHP's HTTP stream wrapper. It's the
   most portable one but relies on a blocking `fopen()`.
 - `CurlHttpClient` relies on the curl extension. It supports full
   concurrency and HTTP/2.

Here are some examples that work with both clients.

For common cases, all the methods on reponses are synchronous:
```php
$client = new NativeHttpClient();

$response = $client->get('https://google.com');

$statusCode = $response->getStatusCode();
$headers = $response->getHeaders();
$content = $response->getContent();
```

When several responses need to be fetched concurrently,
clients provide a `complete()` method, e.g.:

```php
$client = new CurlHttpClient();
$pool = [];

for ($i = 0; $i < 379; ++$i) {
    $pool[] = $client->get("https://http2.akamai.com/demo/tile-$i.png");
}

foreach ($client->complete($pool) as $r) {
    $r->getHeaders();
}
```

The `complete()` method accepts a second `$timeout` argument that defaults
to `ini_get('default_socket_timeout')`, typically 60s. The `foreach` will
skip responses that are *inactive* for longer than the timeout. These
inactive responses are available by calling `$responses->getReturn()`
after iterating is done.

Providing `0` as timeout allows iterating over already completed responses
in a non-blocking way.

When a next response depends on the result of a previous one, it's also
possible to schedule new responses for completion. Doing so is incompatible
with `foreach` and requires using the `Generator` interface directly,
its `send()` method especially:

```php
$client = new CurlHttpClient();

// [...] populate $pool of responses for some first requests as above

$responses = $client->complete($pool);

while ($responses->valid()) {
    $completedResponse = $responses->current();
    $completedKey = $responses->key(); // the key of the response in $pool

    // [...] compute $moreResponses based e.g. on $completedResponse/Key

    if ($moreResponses) {
        $responses->send($moreResponses);
    } else {
        $responses->next();
    }
}
```

By default, clients follow redirections. When the redirection limit is
reached, or when a `4xx` or a `5xx` happens, an exception is thrown.

An array of options allows adjusting the behavior when sending requests.
They are documented in `HttpClientTrait`.

TODO:
 - [ ] validate the design
 - [ ] add tests
 - [ ] split in several PRs?

Implemented:
 - flexible contracts for HTTP clients
 - `fopen()`+`curl`-based clients
 - gzip compression enabled when possible
 - fetch multiple responses concurrently
 - progress function able to cancel the request
 - flexible timeout management
 - public key pinning

Help wanted (can be done after merge):
 - handle standard proxy-related env vars when using `NativeHttpClient`
 - logger integration
 - `TraceableHttpClient` and integration with the profiler
 - `FrameworkBundle` integration: autowireable alias + semantic configuration for default options
 - help clarify the contracts where needed
 - implement bridges with existing HTTP clients in contrib packages
 - mock client

More ideas:
 - HTTP/2 push as a temporary cache in `complete()`
 - cookie jar with a new `"cookie_jar"` option
 - a MIME multipart stream builder
 - make `NativeResponse::getAttribute()` return attributes inspired from `curl_getinfo()`
 - HTTP/HSTS cache
 - etc.

| Q             | A
| ------------- | ---
| Branch?       | master
| Bug fix?      | no
| New feature?  | yes
| BC breaks?    | no
| Deprecations? | no
| Tests pass?   | yes
| Fixed tickets | -
| License       | MIT
| Doc PR        | -

Sooner that later, we'll need to send HTTP calls to APIs,
e.g. Symfony Mailer or symfony#27738 already need it.

Common existing HTTP clients for PHP rely on PSR-7,
which is orthogonal to the way Symfony is designed.

More reasons we need this in core are the package principles:
if we want to be able to keep our BC+deprecation promises, we
have to build on more stable and more abstract dependencies than
Symfony itself.

So here we are. This PR introduces a new `Http` namespace in contracts,
and a new `HttpClient` component.

Its surface is by design very simple to use, while still flexible
enough to cover more advanced use cases thanks to streaming+laziness.

Two full implementations are provided:
 - `NativeHttpClient` is based on PHP's HTTP stream wrapper. It's the
   most portable one but relies on a blocking `fopen()`.
 - `CurlHttpClient` relies on the curl extension. It supports full
   concurrency and HTTP/2.

Here are some examples that work with both clients.

For common cases, all the methods on reponses are synchronous:
```php
$client = new NativeHttpClient();

$response = $client->get('https://google.com');

$statusCode = $response->getStatusCode();
$headers = $response->getHeaders();
$content = $response->getContent();
```

When several responses need to be fetched concurrently,
clients provide a `complete()` method, e.g.:

```php
$client = new CurlHttpClient();
$pool = [];

for ($i = 0; $i < 379; ++$i) {
    $pool[] = $client->get("https://http2.akamai.com/demo/tile-$i.png");
}

foreach ($client->complete($pool) as $r) {
    $r->getHeaders();
}
```

The `complete()` method accepts a second `$timeout` argument that defaults
to `ini_get('default_socket_timeout')`, typically 60s. The `foreach` will
skip responses that are *inactive* for longer than the timeout. These
inactive responses are available by calling `$responses->getReturn()`
after iterating is done.

Providing `0` as timeout allows iterating over already completed responses
in a non-blocking way.

When a next response depends on the result of a previous one, it's also
possible to schedule new responses for completion. Doing so is incompatible
with `foreach` and requires using the `Generator` interface directly,
its `send()` method especially:

```php
$client = new CurlHttpClient();

// [...] populate $pool of responses for some first requests as above

$responses = $client->complete($pool);

while ($responses->valid()) {
    $completedResponse = $responses->current();
    $completedKey = $responses->key(); // the key of the response in $pool

    // [...] compute $moreResponses based e.g. on $completedResponse/Key

    if ($moreResponses) {
        $responses->send($moreResponses);
    } else {
        $responses->next();
    }
}
```

By default, clients follow redirections. When the redirection limit is
reached, or when a `4xx` or a `5xx` happens, an exception is thrown.

An array of options allows adjusting the behavior when sending requests.
They are documented in `HttpClientTrait`.

TODO:
 - [ ] validate the design
 - [ ] add tests
 - [ ] split in several PRs?

Implemented:
 - flexible contracts for HTTP clients
 - `fopen()`+`curl`-based clients
 - gzip compression enabled when possible
 - fetch multiple responses concurrently
 - progress function able to cancel the request
 - flexible timeout management
 - public key pinning

Help wanted (can be done after merge):
 - handle standard proxy-related env vars when using `NativeHttpClient`
 - logger integration
 - `TraceableHttpClient` and integration with the profiler
 - `FrameworkBundle` integration: autowireable alias + semantic configuration for default options
 - help clarify the contracts where needed
 - implement bridges with existing HTTP clients in contrib packages
 - mock client

More ideas:
 - HTTP/2 push as a temporary cache in `complete()`
 - cookie jar with a new `"cookie_jar"` option
 - a MIME multipart stream builder
 - make `NativeResponse::getAttribute()` return attributes inspired from `curl_getinfo()`
 - HTTP/HSTS cache
 - etc.

| Q             | A
| ------------- | ---
| Branch?       | master
| Bug fix?      | no
| New feature?  | yes
| BC breaks?    | no
| Deprecations? | no
| Tests pass?   | yes
| Fixed tickets | -
| License       | MIT
| Doc PR        | -

Sooner that later, we'll need to send HTTP calls to APIs,
e.g. Symfony Mailer or symfony#27738 already need it.

Common existing HTTP clients for PHP rely on PSR-7,
which is orthogonal to the way Symfony is designed.

More reasons we need this in core are the package principles:
if we want to be able to keep our BC+deprecation promises, we
have to build on more stable and more abstract dependencies than
Symfony itself.

So here we are. This PR introduces a new `Http` namespace in contracts,
and a new `HttpClient` component.

Its surface is by design very simple to use, while still flexible
enough to cover more advanced use cases thanks to streaming+laziness.

Two full implementations are provided:
 - `NativeHttpClient` is based on PHP's HTTP stream wrapper. It's the
   most portable one but relies on a blocking `fopen()`.
 - `CurlHttpClient` relies on the curl extension. It supports full
   concurrency and HTTP/2.

Here are some examples that work with both clients.

For common cases, all the methods on reponses are synchronous:
```php
$client = new NativeHttpClient();

$response = $client->get('https://google.com');

$statusCode = $response->getStatusCode();
$headers = $response->getHeaders();
$content = $response->getContent();
```

When several responses need to be fetched concurrently,
clients provide a `complete()` method, e.g.:

```php
$client = new CurlHttpClient();
$pool = [];

for ($i = 0; $i < 379; ++$i) {
    $pool[] = $client->get("https://http2.akamai.com/demo/tile-$i.png");
}

foreach ($client->complete($pool) as $r) {
    $r->getHeaders();
}
```

The `complete()` method accepts a second `$timeout` argument that defaults
to `ini_get('default_socket_timeout')`, typically 60s. The `foreach` will
skip responses that are *inactive* for longer than the timeout. These
inactive responses are available by calling `$responses->getReturn()`
after iterating is done.

Providing `0` as timeout allows iterating over already completed responses
in a non-blocking way.

When a next response depends on the result of a previous one, it's also
possible to schedule new responses for completion. Doing so is incompatible
with `foreach` and requires using the `Generator` interface directly,
its `send()` method especially:

```php
$client = new CurlHttpClient();

// [...] populate $pool of responses for some first requests as above

$responses = $client->complete($pool);

while ($responses->valid()) {
    $completedResponse = $responses->current();
    $completedKey = $responses->key(); // the key of the response in $pool

    // [...] compute $moreResponses based e.g. on $completedResponse/Key

    if ($moreResponses) {
        $responses->send($moreResponses);
    } else {
        $responses->next();
    }
}
```

By default, clients follow redirections. When the redirection limit is
reached, or when a `4xx` or a `5xx` happens, an exception is thrown.

An array of options allows adjusting the behavior when sending requests.
They are documented in `HttpClientTrait`.

TODO:
 - [ ] validate the design
 - [ ] add tests
 - [ ] split in several PRs?

Implemented:
 - flexible contracts for HTTP clients
 - `fopen()`+`curl`-based clients
 - gzip compression enabled when possible
 - fetch multiple responses concurrently
 - progress function able to cancel the request
 - flexible timeout management
 - public key pinning

Help wanted (can be done after merge):
 - handle standard proxy-related env vars when using `NativeHttpClient`
 - logger integration
 - `TraceableHttpClient` and integration with the profiler
 - `FrameworkBundle` integration: autowireable alias + semantic configuration for default options
 - help clarify the contracts where needed
 - implement bridges with existing HTTP clients in contrib packages
 - mock client

More ideas:
 - HTTP/2 push as a temporary cache in `complete()`
 - cookie jar with a new `"cookie_jar"` option
 - helpers to send JSONs/forms/uploads via special type in "body" option
 - make `NativeResponse::getAttribute()` return attributes inspired from `curl_getinfo()`
 - use raw sockets instead of the HTTP stream wrapper
 - HTTP/HSTS cache
 - etc.

| Q             | A
| ------------- | ---
| Branch?       | master
| Bug fix?      | no
| New feature?  | yes
| BC breaks?    | no
| Deprecations? | no
| Tests pass?   | yes
| Fixed tickets | -
| License       | MIT
| Doc PR        | -

Sooner that later, we'll need to send HTTP calls to APIs,
e.g. Symfony Mailer or symfony#27738 already need it.

Common existing HTTP clients for PHP rely on PSR-7,
which is orthogonal to the way Symfony is designed.

More reasons we need this in core are the package principles:
if we want to be able to keep our BC+deprecation promises, we
have to build on more stable and more abstract dependencies than
Symfony itself.

So here we are. This PR introduces a new `Http` namespace in contracts,
and a new `HttpClient` component.

Its surface is by design very simple to use, while still flexible
enough to cover more advanced use cases thanks to streaming+laziness.

Two full implementations are provided:
 - `NativeHttpClient` is based on PHP's HTTP stream wrapper. It's the
   most portable one but relies on a blocking `fopen()`.
 - `CurlHttpClient` relies on the curl extension. It supports full
   concurrency and HTTP/2.

Here are some examples that work with both clients.

For common cases, all the methods on reponses are synchronous:
```php
$client = new NativeHttpClient();

$response = $client->get('https://google.com');

$statusCode = $response->getStatusCode();
$headers = $response->getHeaders();
$content = $response->getContent();
```

When several responses need to be fetched concurrently,
clients provide a `complete()` method, e.g.:

```php
$client = new CurlHttpClient();
$pool = [];

for ($i = 0; $i < 379; ++$i) {
    $pool[] = $client->get("https://http2.akamai.com/demo/tile-$i.png");
}

foreach ($client->complete($pool) as $r) {
    $r->getHeaders();
}
```

The `complete()` method accepts a second `$timeout` argument that defaults
to `ini_get('default_socket_timeout')`, typically 60s. The `foreach` will
skip responses that are *inactive* for longer than the timeout. These
inactive responses are available by calling `$responses->getReturn()`
after iterating is done.

Providing `0` as timeout allows iterating over already completed responses
in a non-blocking way.

When a next response depends on the result of a previous one, it's also
possible to schedule new responses for completion. Doing so is incompatible
with `foreach` and requires using the `Generator` interface directly,
its `send()` method especially:

```php
$client = new CurlHttpClient();

// [...] populate $pool of responses for some first requests as above

$responses = $client->complete($pool);

while ($responses->valid()) {
    $completedResponse = $responses->current();
    $completedKey = $responses->key(); // the key of the response in $pool

    // [...] compute $moreResponses based e.g. on $completedResponse/Key

    if ($moreResponses) {
        $responses->send($moreResponses);
    } else {
        $responses->next();
    }
}
```

By default, clients follow redirections. When the redirection limit is
reached, or when a `4xx` or a `5xx` happens, an exception is thrown.

An array of options allows adjusting the behavior when sending requests.
They are documented in `HttpClientTrait`.

TODO:
 - [ ] validate the design
 - [ ] add tests
 - [ ] split in several PRs?

Implemented:
 - flexible contracts for HTTP clients
 - `fopen()` + `curl`-based clients
 - gzip compression enabled when possible
 - fetch multiple responses concurrently
 - progress function able to cancel the request
 - flexible timeout management
 - public key pinning

Help wanted (can be done after merge):
 - handle standard proxy-related env vars when using `NativeHttpClient`
 - logger integration
 - `TraceableHttpClient` and integration with the profiler
 - `FrameworkBundle` integration: autowireable alias + semantic configuration for default options
 - help clarify the contracts where needed
 - mock client

More ideas:
 - HTTP/2 push as a temporary cache in `complete()`
 - cookie jar with a new `"cookie_jar"` option
 - helpers to send JSONs/forms/uploads via special type in "body" option
 - make `NativeResponse::getAttribute()` return attributes inspired from `curl_getinfo()`
 - use raw sockets instead of the HTTP stream wrapper
 - HTTP/HSTS cache
 - implement bridges with existing HTTP clients
 - etc.

| Q             | A
| ------------- | ---
| Branch?       | master
| Bug fix?      | no
| New feature?  | yes
| BC breaks?    | no
| Deprecations? | no
| Tests pass?   | yes
| Fixed tickets | -
| License       | MIT
| Doc PR        | -

Sooner that later, we'll need to send HTTP calls to APIs,
e.g. Symfony Mailer or symfony#27738 already need it.

Common existing HTTP clients for PHP rely on PSR-7,
which is orthogonal to the way Symfony is designed.

More reasons we need this in core are the package principles:
if we want to be able to keep our BC+deprecation promises, we
have to build on more stable and more abstract dependencies than
Symfony itself.

So here we are. This PR introduces a new `Http` namespace in contracts,
and a new `HttpClient` component.

Its surface is by design very simple to use, while still flexible
enough to cover more advanced use cases thanks to streaming+laziness.

Two full implementations are provided:
 - `NativeHttpClient` is based on PHP's HTTP stream wrapper. It's the
   most portable one but relies on a blocking `fopen()`.
 - `CurlHttpClient` relies on the curl extension. It supports full
   concurrency and HTTP/2.

Here are some examples that work with both clients.

For common cases, all the methods on reponses are synchronous:
```php
$client = new NativeHttpClient();

$response = $client->get('https://google.com');

$statusCode = $response->getStatusCode();
$headers = $response->getHeaders();
$content = $response->getContent();
```

When several responses need to be fetched concurrently,
clients provide a `complete()` method, e.g.:

```php
$client = new CurlHttpClient();
$pool = [];

for ($i = 0; $i < 379; ++$i) {
    $pool[] = $client->get("https://http2.akamai.com/demo/tile-$i.png");
}

foreach ($client->complete($pool) as $r) {
    $r->getHeaders();
}
```

The `complete()` method accepts a second `$timeout` argument that defaults
to `ini_get('default_socket_timeout')`, typically 60s. The `foreach` will
skip responses that are *inactive* for longer than the timeout. These
inactive responses are available by calling `$responses->getReturn()`
after iterating is done.

Providing `0` as timeout allows iterating over already completed responses
in a non-blocking way.

When a next response depends on the result of a previous one, it's also
possible to schedule new responses for completion. Doing so is incompatible
with `foreach` and requires using the `Generator` interface directly,
its `send()` method especially:

```php
$client = new CurlHttpClient();

// [...] populate $pool of responses for some first requests as above

$responses = $client->complete($pool);

while ($responses->valid()) {
    $completedResponse = $responses->current();
    $completedKey = $responses->key(); // the key of the response in $pool

    // [...] compute $moreResponses based e.g. on $completedResponse/Key

    if ($moreResponses) {
        $responses->send($moreResponses);
    } else {
        $responses->next();
    }
}
```

By default, clients follow redirections. When the redirection limit is
reached, or when a `4xx` or a `5xx` happens, an exception is thrown.

An array of options allows adjusting the behavior when sending requests.
They are documented in `HttpClientTrait`.

TODO:
 - [ ] validate the design
 - [ ] add tests
 - [ ] split in several PRs?

Implemented:
 - flexible contracts for HTTP clients
 - `fopen()` + `curl`-based clients
 - gzip compression enabled when possible
 - fetch multiple responses concurrently
 - progress function able to cancel the request
 - flexible timeout management
 - public key pinning

Help wanted (can be done after merge):
 - handle standard proxy-related env vars when using `NativeHttpClient`
 - logger integration
 - `TraceableHttpClient` and integration with the profiler
 - `FrameworkBundle` integration: autowireable alias + semantic configuration for default options
 - help clarify the contracts where needed
 - mock client

More ideas:
 - HTTP/2 push as a temporary cache in `complete()`
 - cookie jar with a new `"cookie_jar"` option
 - helpers to send JSONs/forms/uploads via special type in "body" option
 - make `NativeResponse::getAttribute()` return attributes inspired from `curl_getinfo()`
 - use raw sockets instead of the HTTP stream wrapper
 - HTTP/HSTS cache
 - implement bridges with existing HTTP clients
 - etc.

| Q             | A
| ------------- | ---
| Branch?       | master
| Bug fix?      | no
| New feature?  | yes
| BC breaks?    | no
| Deprecations? | no
| Tests pass?   | yes
| Fixed tickets | -
| License       | MIT
| Doc PR        | -

Sooner that later, we'll need to send HTTP calls to APIs,
e.g. Symfony Mailer or symfony#27738 already need it.

Common existing HTTP clients for PHP rely on PSR-7,
which is orthogonal to the way Symfony is designed.

More reasons we need this in core are the package principles:
if we want to be able to keep our BC+deprecation promises, we
have to build on more stable and more abstract dependencies than
Symfony itself.

So here we are. This PR introduces a new `Http` namespace in contracts,
and a new `HttpClient` component.

Its surface is by design very simple to use, while still flexible
enough to cover more advanced use cases thanks to streaming+laziness.

Two full implementations are provided:
 - `NativeHttpClient` is based on PHP's HTTP stream wrapper. It's the
   most portable one but relies on a blocking `fopen()`.
 - `CurlHttpClient` relies on the curl extension. It supports full
   concurrency and HTTP/2.

Here are some examples that work with both clients.

For common cases, all the methods on reponses are synchronous:
```php
$client = new NativeHttpClient();

$response = $client->get('https://google.com');

$statusCode = $response->getStatusCode();
$headers = $response->getHeaders();
$content = $response->getContent();
```

When several responses need to be fetched concurrently,
clients provide a `complete()` method, e.g.:

```php
$client = new CurlHttpClient();
$pool = [];

for ($i = 0; $i < 379; ++$i) {
    $pool[] = $client->get("https://http2.akamai.com/demo/tile-$i.png");
}

foreach ($client->complete($pool) as $r) {
    $r->getHeaders();
}
```

The `complete()` method accepts a second `$timeout` argument that defaults
to `ini_get('default_socket_timeout')`, typically 60s. The `foreach` will
skip responses that are *inactive* for longer than the timeout. These
inactive responses are available by calling `$responses->getReturn()`
after iterating is done.

Providing `0` as timeout allows iterating over already completed responses
in a non-blocking way.

When a next response depends on the result of a previous one, it's also
possible to schedule new responses for completion. Doing so is incompatible
with `foreach` and requires using the `Generator` interface directly,
its `send()` method especially:

```php
$client = new CurlHttpClient();

// [...] populate $pool of responses for some first requests as above

$responses = $client->complete($pool);

while ($responses->valid()) {
    $completedResponse = $responses->current();
    $completedKey = $responses->key(); // the key of the response in $pool

    // [...] compute $moreResponses based e.g. on $completedResponse/Key

    if ($moreResponses) {
        $responses->send($moreResponses);
    } else {
        $responses->next();
    }
}
```

By default, clients follow redirections. When the redirection limit is
reached, or when a `4xx` or a `5xx` happens, an exception is thrown.

An array of options allows adjusting the behavior when sending requests.
They are documented in `HttpClientTrait`.

TODO:
 - [ ] validate the design
 - [ ] add tests
 - [ ] split in several PRs?

Implemented:
 - flexible contracts for HTTP clients
 - `fopen()` + `curl`-based clients
 - gzip compression enabled when possible
 - fetch multiple responses concurrently
 - progress function able to cancel the request
 - flexible timeout management
 - public key pinning

Help wanted (can be done after merge):
 - handle standard proxy-related env vars when using `NativeHttpClient`
 - logger integration
 - `TraceableHttpClient` and integration with the profiler
 - `FrameworkBundle` integration: autowireable alias + semantic configuration for default options
 - help clarify the contracts where needed
 - mock client

More ideas:
 - HTTP/2 push as a temporary cache in `complete()`
 - cookie jar with a new `"cookie_jar"` option
 - helpers to send JSONs/forms/uploads via special type in "body" option
 - make `NativeResponse::getAttribute()` return attributes inspired from `curl_getinfo()`
 - use raw sockets instead of the HTTP stream wrapper
 - HTTP/HSTS cache
 - implement bridges with existing HTTP clients
 - etc.

| Q             | A
| ------------- | ---
| Branch?       | master
| Bug fix?      | no
| New feature?  | yes
| BC breaks?    | no
| Deprecations? | no
| Tests pass?   | yes
| Fixed tickets | -
| License       | MIT
| Doc PR        | -

Sooner that later, we'll need to send HTTP calls to APIs,
e.g. Symfony Mailer or symfony#27738 already need it.

Common existing HTTP clients for PHP rely on PSR-7, which is orthogonal
to the way Symfony is designed and thus we don't want to push in core.

More reasons we need this in core are the package principles:
if we want to be able to keep our BC+deprecation promises, we
have to build on more stable and more abstract dependencies than
Symfony itself.

So here we are. This PR introduces a new `Http` namespace in contracts,
and a new `HttpClient` component.

Its surface is by design very simple to use, while still flexible
enough to cover more advanced use cases thanks to streaming+laziness.

Two full implementations are provided:
 - `NativeHttpClient` is based on PHP's HTTP stream wrapper. It's the
   most portable one but relies on a blocking `fopen()`.
 - `CurlHttpClient` relies on the curl extension. It supports full
   concurrency and HTTP/2.

Here are some examples that work with both clients.

For common cases, all the methods on reponses are synchronous:
```php
$client = new NativeHttpClient();

$response = $client->get('https://google.com');

$statusCode = $response->getStatusCode();
$headers = $response->getHeaders();
$content = $response->getContent();
```

When several responses need to be fetched concurrently,
clients provide a `complete()` method, e.g.:

```php
$client = new CurlHttpClient();
$pool = [];

for ($i = 0; $i < 379; ++$i) {
    $pool[] = $client->get("https://http2.akamai.com/demo/tile-$i.png");
}

foreach ($client->complete($pool) as $r) {
    $r->getHeaders();
}
```

The `complete()` method accepts a second `$timeout` argument that defaults
to `ini_get('default_socket_timeout')`, typically 60s. The `foreach` will
skip responses that are *inactive* for longer than the timeout. These
inactive responses are available by calling `$responses->getReturn()`
after iterating is done.

Providing `0` as timeout allows iterating over already completed responses
in a non-blocking way.

When a next response depends on the result of a previous one, it's also
possible to schedule new responses for completion. Doing so is incompatible
with `foreach` and requires using the `Generator` interface directly,
its `send()` method especially:

```php
$client = new CurlHttpClient();

// [...] populate $pool of responses for some first requests as above

$responses = $client->complete($pool);

while ($responses->valid()) {
    $completedResponse = $responses->current();
    $completedKey = $responses->key(); // the key of the response in $pool

    // [...] compute $moreResponses based e.g. on $completedResponse/Key

    if ($moreResponses) {
        $responses->send($moreResponses);
    } else {
        $responses->next();
    }
}
```

By default, clients follow redirections. When the redirection limit is
reached, or when a `4xx` or a `5xx` happens, an exception is thrown.

An array of options allows adjusting the behavior when sending requests.
They are documented in `HttpClientTrait`.

TODO:
 - [ ] validate the design
 - [ ] add tests
 - [ ] split in several PRs?

Implemented:
 - flexible contracts for HTTP clients
 - `fopen()` + `curl`-based clients
 - gzip compression enabled when possible
 - fetch multiple responses concurrently
 - progress function able to cancel the request
 - flexible timeout management
 - public key pinning

Help wanted (can be done after merge):
 - handle standard proxy-related env vars when using `NativeHttpClient`
 - logger integration
 - `TraceableHttpClient` and integration with the profiler
 - `FrameworkBundle` integration: autowireable alias + semantic configuration for default options
 - help clarify the contracts where needed
 - mock client

More ideas:
 - HTTP/2 push as a temporary cache in `complete()`
 - cookie jar with a new `"cookie_jar"` option
 - helpers to send JSONs/forms/uploads via special type in "body" option
 - make `NativeResponse::getAttribute()` return attributes inspired from `curl_getinfo()`
 - use raw sockets instead of the HTTP stream wrapper
 - HTTP/HSTS cache
 - implement bridges with existing HTTP clients
 - etc.

| Q             | A
| ------------- | ---
| Branch?       | master
| Bug fix?      | no
| New feature?  | yes
| BC breaks?    | no
| Deprecations? | no
| Tests pass?   | yes
| Fixed tickets | -
| License       | MIT
| Doc PR        | -

Sooner that later, we'll need to send HTTP calls to APIs,
e.g. Symfony Mailer or symfony#27738 already need it.

Common existing HTTP clients for PHP rely on PSR-7, which is complex and
orthogonal to the way Symfony is designed.

More reasons we need this in core are the package principles:
if we want to be able to keep our BC+deprecation promises, we
have to build on more stable and more abstract dependencies than
Symfony itself.

So here we are. This PR introduces a new `Http` namespace in contracts,
and a new `HttpClient` component.

Its surface is by design very simple to use, while still flexible
enough to cover more advanced use cases thanks to streaming+laziness.

Two full implementations are provided:
 - `NativeHttpClient` is based on PHP's HTTP stream wrapper. It's the
   most portable one but relies on a blocking `fopen()`.
 - `CurlHttpClient` relies on the curl extension. It supports full
   concurrency and HTTP/2.

Here are some examples that work with both clients.

For common cases, all the methods on reponses are synchronous:
```php
$client = new NativeHttpClient();

$response = $client->get('https://google.com');

$statusCode = $response->getStatusCode();
$headers = $response->getHeaders();
$content = $response->getContent();
```

When several responses need to be fetched concurrently,
clients provide a `complete()` method, e.g.:

```php
$client = new CurlHttpClient();
$pool = [];

for ($i = 0; $i < 379; ++$i) {
    $pool[] = $client->get("https://http2.akamai.com/demo/tile-$i.png");
}

foreach ($client->complete($pool) as $r) {
    $r->getHeaders();
}
```

The `complete()` method accepts a second `$timeout` argument that defaults
to `ini_get('default_socket_timeout')`, typically 60s. The `foreach` will
skip responses that are *inactive* for longer than the timeout. These
inactive responses are available by calling `$responses->getReturn()`
after iterating is done.

Providing `0` as timeout allows iterating over already completed responses
in a non-blocking way.

When a next response depends on the result of a previous one, it's also
possible to schedule new responses for completion. Doing so is incompatible
with `foreach` and requires using the `Generator` interface directly,
its `send()` method especially:

```php
$client = new CurlHttpClient();

// [...] populate $pool of responses for some first requests as above

$responses = $client->complete($pool);

while ($responses->valid()) {
    $completedResponse = $responses->current();
    $completedKey = $responses->key(); // the key of the response in $pool

    // [...] compute $moreResponses based e.g. on $completedResponse/Key

    if ($moreResponses) {
        $responses->send($moreResponses);
    } else {
        $responses->next();
    }
}
```

By default, clients follow redirections. When the redirection limit is
reached, or when a `4xx` or a `5xx` happens, an exception is thrown.

An array of options allows adjusting the behavior when sending requests.
They are documented in `HttpClientTrait`.

TODO:
 - [ ] validate the design
 - [ ] add tests

Implemented:
 - flexible contracts for HTTP clients
 - `fopen()` + `curl`-based clients
 - gzip compression enabled when possible
 - fetch multiple responses concurrently
 - progress function able to cancel the request
 - flexible timeout management
 - public key pinning

Help wanted (can be done after merge):
 - handle standard proxy-related env vars when using `NativeHttpClient`
 - logger integration
 - `TraceableHttpClient` and integration with the profiler
 - `FrameworkBundle` integration: autowireable alias + semantic configuration for default options
 - help clarify the contracts where needed
 - mock client

More ideas:
 - HTTP/2 push as a temporary cache in `complete()`
 - cookie jar with a new `"cookie_jar"` option
 - helpers to send JSONs/forms/uploads via special type in "body" option
 - make `NativeResponse::getAttribute()` return attributes inspired from `curl_getinfo()`
 - use raw sockets instead of the HTTP stream wrapper
 - HTTP/HSTS cache
 - implement bridges with existing HTTP clients
 - etc.