[PHP 8.1] Add a shim to Guzzle 6 for PHP 8.1 compatibility

I'm undecided if we should push back a bit on https://github.com/guzzle/guzzle/pull/2918 and point out that is something is security supported then it needs to work on all supported PHP versions. They could reasonably say that triggering a deprecation doesn't mean anything is broken.

That said, this is an elegant fix that buys us sometime to potentially sort out Guzzle 7 compatibility in Drupal 9 without the pressure of the PHP 8.1 release date.

I've added this shim to #3220021: [meta] Ensure compatibility of Drupal 9 with PHP 8.1 (as it evolves) and it fixes the PHP 8.1 deprecation notices due to Guzzle 6.

I think I would probably go for:

1. Commit this anyway

2. Work on Guzzle 7 compatibility - we need it for 10.x anyway.

3. If we hit problems with Guzzle 7 (apart from our own min/max testing issues which aren't their fault), then go back to ask for a commt.

Needs a re-roll. I've bumped the Guzzle 7 issues.

I think we're leaning toward doing #3187315: Remove mink-goutte-driver as a core dependency in 9.3.x given the low risk of disruption. However, I think we should also still do this issue, because there are some more disruptive changes between Guzzle 6 and 7. We've already addressed the ones that affected core, but there are a number of things that could affect other projects as well.

We can also open an issue to consider making our constraint be:
"guzzlehttp/guzzle": "^6.5.2 || ^7.3.0",
...but keep core-recommended pinned at the lower version and use the min/max retesting workaround to ensure we stay forward-compatible with Guzzle 7.

Guzzle 6 compatibility with PHP 8.1 has gotten a bit more complex with the latest round of deprecations in PHP. Classes which extend \Countable and \IteratorAggregate so \GuzzleHttp\Cookie\CookieJar::count(), \GuzzleHttp\Cookie\CookieJar::getIterator() and \GuzzleHttp\Handler\MockHandler::count() all need the annotation #[\ReturnTypeWillChange] added to avoid PHP 8.1 emitting the deprecation. And I wouldn't be surprised if there were more deprecations by the end of the beta cycle. PHP 8.1 seems to be in the process of tightening quite a few things up.

Just re-rolled the patch in #2, thanks!

fix checksum COMPOSER_ROOT_VERSION=9.3.x-dev composer update --lock

Given #9 we're going to need to come up with another plan or extend this one using class aliases.

Posted #3225966: Consider loosening our constraint to allow sites to install Guzzle 6 or 7, or otherwise handle PHP 8.1 deprecations for Guzzle 6.

In #3220021: [meta] Ensure compatibility of Drupal 9 with PHP 8.1 (as it evolves) we've managed to work around the deprecations triggered by Guzzle. I think potentially we should continue on here with the shim and ignore the deprecations and be able to do #3225966: Consider loosening our constraint to allow sites to install Guzzle 6 or 7, or otherwise handle PHP 8.1 deprecations for Guzzle 6 at more leisurely pace.

I think we should add a test with the second parameter being NULL in combination with PHP 8.1.

I think we shall have to choose how we are going to fix this. To me the possible options are:

1. Keep Guzzle version 6 and do not support PHP 8.1 on D9.3. Support for PHP 8.1 shall have to wait for D10. To me, this is not a very acceptable option.
2. Upgrade to Guzzle version 7 and have PHP 8.1 support on D9.3. D9.3 sites that depend on Guzzle 6 will break. There will not be many sites out there, but supporting PHP 8.1 on D9.3 is just far more important. We can allow sites to downgrade to Guzzle version 6, only then for those sites no more PHP 8.1 support.
3. Maintain 2 different D9.3 branches, one for Guzzle 6 and one for Guzzle 7. Will be more work to maintain, more work (and cost) for the testbot. It is doable, only not very attractive. Also a lot of communication to the Drupal community about the 2 branches and how they are different.
4. Pay the maintainers of Guzzle to support PHP 8.1 on Guzzle version 6. Lets ask them if that is interesting to them and if so, how much will it cost. Use the Drupal community to ask which sites are on D9 and will break when we upgrade to Guzzle version 7. Ask those site owners for the money to pay the Guzzle maintainers. Tell those site owners that the alternative is option #2. Also is it an option that the Drupal Association put in some or all of the money.

For me is option #4 to most attractive, because D9.3 can stay on Guzzle version 6 and have support for PHP 8.1. When this is not possible then for me it would be option #2.

Fixing this for D9.3 is critical.

@daffie we can use Guzzle 6 on PHP 8.1 if we do the patch here and skip some deprecations - that's working just fine on #3220021: [meta] Ensure compatibility of Drupal 9 with PHP 8.1 (as it evolves). Re #17 - I don't think we need an explicit test here. Once we have testing on PHP 8.1 we get test coverage - we can't have that yet because the test suite does not pass because of issues like this.

I think there is a lot of value changing the constraints to allow Guzzle 7 in Drupal 9 but then we're back to the old min/max testing issue that we've still not solved and I think we can use the approach in this issue and deprecation skipping to get us PHP 8.1 compatibility without having to solve that.

Given the explanation of @alexpott in comment #20, the patch looks good to me.
The shim is added, when the parameter $numeric_prefix is null the value is changed to an empty array.
The docblock is copied from the PHP manual.
For me it is RTBC.

#13 needs a re-roll.

Just rerolled patch in #13, thanks!

Rerolled.

This is great. We can continue looking at Guzzle updates within 9.3.x in the follow-up.