bug #30967 [HttpClient] Document the state object that is passed around by the HttpClient (derrabus)

This PR was merged into the 4.3-dev branch.

Discussion
----------

[HttpClient] Document the state object that is passed around by the HttpClient

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

In an attempt to make the code of the new HttpClient component more understandable, I've introduced internal classes that document the `$multi` object that is being passed around between *Client and *Response classes.

My goal is to make the code more accessible to potential contributors and static code analyzers.

Commits
-------

20f4eb3204 Document the state object that is passed around by the HttpClient.

This PR was merged into the 4.3-dev branch.

Discussion
----------

Fixes unmapped parameter for an error message in HttpClientTrait

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

Commits
-------

b9e2046821 Fixes sprintf unmapped parameter.

feature #30843 [HttpClient] Add ScopingHttpClient::forBaseUri() + tweak MockHttpClient (nicolas-grekas)

This PR was merged into the 4.3-dev branch.

Discussion
----------

[HttpClient] Add ScopingHttpClient::forBaseUri() + tweak MockHttpClient

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

This allows creating scoped HTTP clients in one line:

```php
$client = ScopingHttpClient::forBaseUri($client, 'http://example.com');
```

`$client` now resolves relative URLs using the provided base URI.

If one also adds default options as 3rd argument, these will be applied conditionally when a URL matching the base URI is requested.

This PR also tweaks `MockHttpClient` to make it return `MockResponse` on its own when no constructor argument is provided, easing tests a bit.

Commits
-------

2b9b8e5707 [HttpClient] Add ScopingHttpClient::forBaseUri() + tweak MockHttpClient

This PR was merged into the 4.3-dev branch.

Discussion
----------

[HttpClient] use "nyholm/psr7" by default in Psr18Client

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

This makes the factory arguments of `Psr18Client` optional, with a fallback to using `Nyholm\Psr7\Factory\Psr17Factory` when no factories are provided.

Commits
-------

f2222e4bf5 [HttpClient] use "nyholm/psr7" by default in Psr18Client

This PR was squashed before being merged into the 4.3-dev branch (closes #30559).

Discussion
----------

[HttpClient] Parse common API error formats for better exception messages

| Q             | A
| ------------- | ---
| Branch?       | master <!-- see below -->
| Bug fix?      | no
| New feature?  | yes <!-- don't forget to update src/**/CHANGELOG.md files -->
| BC breaks?    | no     <!-- see https://symfony.com/bc -->
| Deprecations? | no <!-- don't forget to update UPGRADE-*.md and src/**/CHANGELOG.md files -->
| Tests pass?   | yes    <!-- please add some, will be required by reviewers -->
| Fixed tickets | n/a  <!-- #-prefixed issue number(s), if any -->
| License       | MIT
| Doc PR        | todo?

Use extra details provided by popular error formats following to improve HTTP exception messages.
The following formats are supported:

* Hydra (default in API Platform)
* RFC 7807 (followed by Symfony's [ConstraintViolationListNormalizer](https://github.com/symfony/symfony/blob/master/src/Symfony/Component/Serializer/Normalizer/ConstraintViolationListNormalizer.php) and supported by API Platform and Apigility)
* JSON:API (because it respects the semantic of the RFC 7807)

It allows to write code like the following (here in a test context):

```php
    public function testBadRequest()
    {
        $this->expectException(ClientExceptionInterface::class);
        $this->expectExceptionCode(400); // HTTP status code
        $this->expectExceptionMessage(<<<ERROR
Validation Failed

users: This collection should contain 1 element or more.
users: The current logged in user must be part of the users owning this resource.
ERROR
);

        $response = (HttpClient::create())->request('POST', 'http://example.com/api/projects', [
            'json' => [
                'name' => 'My project',
            ],
        ]);
        $response->getContent();
    }
```

Port of https://github.com/api-platform/core/pull/2608#issuecomment-472510732.

Commits
-------

96df4464a1 [HttpClient] Parse common API error formats for better exception messages

This PR was merged into the 4.3-dev branch.

Discussion
----------

[HttpClient] added CachingHttpClient

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

The proposed `CachingHttpClient` uses `HttpCache` from the HttpKernel component to provide an HTTP-compliant cache.

If this is accepted, it could replace the corresponding part in #30602

Commits
-------

dae5686722 [HttpClient] added CachingHttpClient

This PR was merged into the 4.3-dev branch.

Discussion
----------

[BrowserKit] Add support for HttpClient

| Q             | A
| ------------- | ---
| Branch?       | master
| Bug fix?      | no
| New feature?  | yes
| BC breaks?    | no
| Deprecations? | no <!-- don't forget to update UPGRADE-*.md and src/**/CHANGELOG.md files -->
| Tests pass?   | yes    <!-- please add some, will be required by reviewers -->
| Fixed tickets | part of #30502
| License       | MIT
| Doc PR        | not yet

When combining the power of the new HttpClient component with the BrowserKit and Mime components, we can makes something really powerful... a full/better/awesome replacement for https://github.com/FriendsOfPHP/Goutte.

So, this PR is about integrating the HttpClient component with BrowserKit to give users a high-level interface to ease usages in the most common use cases.

Scraping websites can be done like this:

```php
use Symfony\Component\BrowserKit\HttpBrowser;
use Symfony\Component\HttpClient\HttpClient;

$client = HttpClient::create();
$browser = new HttpBrowser($client);

$browser->request('GET', 'https://example.com/');
$browser->clickLink('Log In');
$browser->submitForm('Sign In', ['username' => 'me', 'password' => 'pass']);
$browser->clickLink('Subscriptions')->filter('table tr:nth-child(2) td:nth-child(2)')->each(function ($node) {
    echo trim($node->text())."\n";
});
```

And voilà! Nice, isn't?

Want to add HTTP cache? Sure:

```php
use Symfony\Component\HttpKernel\HttpCache\Store;

$client = HttpClient::create();
$store = new Store(sys_get_temp_dir().'/http-cache-store');

$browser = new HttpBrowser($client, $store);

// ...
```

Want logging and debugging of HTTP Cache? Yep:

```php
use Psr\Log\AbstractLogger;

class EchoLogger extends AbstractLogger
{
    public function log($level, $message, array $context = [])
    {
        echo $message."\n";
    }
}

$browser = new HttpBrowser($client, $store, new EchoLogger());
```

The first time you run your code, you will get an output similar to:

```
Request: GET https://twig.symfony.com/
Response: 200 https://twig.symfony.com/
Cache: GET /: miss, store
Request: GET https://twig.symfony.com/doc/2.x/
Response: 200 https://twig.symfony.com/doc/2.x/
Cache: GET /doc/2.x/: miss, store
```

But then:

```
Cache: GET /: fresh
Cache: GET /doc/2.x/: fresh
```

Limit is the sky here as you get the full power of all the Symfony ecosystem.

Under the hood, these examples leverage HttpFoundation, HttpKernel (with HttpCache),
DomCrawler, BrowserKit, CssSelector, HttpClient, Mime, ...

Excited?

P.S. : Tests need to wait for the HttpClient Mock class to land into master.

Commits
-------

b5b2a2557c Add tests for HttpBrowser
dd55845706 [BrowserKit] added support for HttpClient

This PR was merged into the 4.3-dev branch.

Discussion
----------

[HttpClient] add MockHttpClient

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

This PR introduces `MockHttpClient` and `MockResponse`, to be used for testing classes that need an HTTP client without making actual HTTP requests.

`MockHttpClient` is configured via its constructor: you provide it either with an iterable or a callable, and these will be used to provide responses as the consumer requests them.

Example:
```php
$responses = [
    new MockResponse($body1, $info1),
    new MockResponse($body2, $info2),
];

$client = new MockHttpClient($responses);
$response1 = $client->request(...); // created from $responses[0]
$response2 = $client->request(...); // created from $responses[1]
```

Or alternatively:
```php
$callback = function ($method, $url, $options) {
    return new MockResponse(...);
};

$client = new MockHttpClient($callback);
$response = $client->request(...); // calls $callback internal
```

The responses provided to the client don't have to be instances of `MockResponse` - any `ResponseInterface` works (e.g. `$this->getMockBuilder(ResponseInterface::class)->getMock()`).

Using `MockResponse` allows simulating chunked responses and timeouts:
```php
$body = function () {
    yield 'hello';
    yield ''; // the empty string is turned into a timeout so that they are easy to test
    yield 'world';
};
$mockResponse = new Mockresponse($body);
```

Last but not least, the implementation simulates the full lifecycle of a properly behaving `HttpClientInterface` contracts implementation: error handling, progress function, etc. This is "proved" by `MockHttpClientTest`, who implements and passes the reference test suite in `HttpClientTestCase`.

Commits
-------

8fd7584158 [HttpClient] add MockHttpClient

This PR was squashed before being merged into the 4.3-dev branch (closes #30567).

Discussion
----------

[HttpClient] exceptions carry response

| Q             | A
| ------------- | ---
| Branch?       | master
| Bug fix?      | no
| New feature?  | yes
| BC breaks?    | no     <!-- see https://symfony.com/bc -->
| Deprecations? | no
| Tests pass?   | yes    <!-- please add some, will be required by reviewers -->
| Fixed tickets | #30502
| License       | MIT
| Doc PR        |

Commits
-------

103448cc67 [HttpClient] exceptions carry response

This PR was squashed before being merged into the 4.3-dev branch (closes #30549).

Discussion
----------

[HttpClient] Make exceptions public

| Q             | A
| ------------- | ---
| Branch?       | master
| Bug fix?      | no
| New feature?  | no<!-- don't forget to update src/**/CHANGELOG.md files -->
| BC breaks?    | no     <!-- see https://symfony.com/bc -->
| Deprecations? | no <!-- don't forget to update UPGRADE-*.md and src/**/CHANGELOG.md files -->
| Tests pass?   | yes    <!-- please add some, will be required by reviewers -->
| Fixed tickets | #...   <!-- #-prefixed issue number(s), if any -->
| License       | MIT
| Doc PR        | n/a

Makes it easier to implement the interface. See api-platform/core#2608

Commits
-------

928d774e4a [HttpClient] Make exceptions public