This PR assumed a decoration like this is the intended way:

services:
     decorated.http_client:
          class: HttpClientDecorator
          arguments: [decorated.http_client.inner]
          decorates: http_client
          decoration_priority: 10

Issues like this getsentry/sentry-symfony#700 show, it is not clear how to decorate (all ways http clients can be bootstrapped) in the correct way.

Friendly ping @nicolas-grekas

I'm not sure it makes sense documenting this. What Sentry does is uncommon to me.

I searches around how the http client had been decorated in examples, issues and more. It shows there is a bigger diversity but in general there aren't that many sources, if you search for help.
Decoration is communicated to be the key extension tool and imho it is not enough to just point to the general decoration document while it is unclear what exactly to decorate and how it behaves in the different ways the clients can be bootstrapped.
It is kinda offtopic to the current state of the PR, but I could extend it to make decoration more clear and show the intended way.

Here are sources where others decorated the scoped clients:

• HttpClient decoration with nested AsyncResponse instances problem symfony#49246
• https://jolicode.com/blog/aggressive-caching-with-symfony-http-client

If the tagged clients are decorated, the decorator does not receive the final URL which should cause issues in may use cases.
Additionally the decorator is twice in the chain as the sentry issue shows. I did not really debug how this happen, but most likely because the default http_client service as well as the scoped http service are decorated and "merged together" in a later step.
On the other hand If the http_client service is decorated, we need a minimum priority of 5/6 because otherwise the scoped clients are already decorated, when our decoration would be processed which could maybe considered an resolvable issue. At least to me it is hidden knowledge you can just find out by try and error or could end up doing exactly this tagged client decoration, because your own decorator does not appear otherwise.

This made me realize that symfony/symfony#49513 should have solved this issue with decoration. This could be worth documenting.
(But I wouldn't document what you describe, it's too niche to me and it should be obsoleted by this PR.)

I prefer a different way of documenting this as well, especially would prefer a fix for this :)
To me this is no niche scenario tho. When sentry fixes its decoration, they are most likely very much effected to decide of a priority and cant stick to zero.
Actually everyone is affected that want to use scoped clients or third party libraries like sentry that do not know how the clients are created.

friendly ping @fancyweb, as you are the author of

• [FrameworkBundle][HttpClient] Refactor http_client decoration strategy symfony#49513

After reading the entire discussion, let's close this one as "won't merge" ... and let's add the missing docs about the new HttpClient decoration strategy in #19363. Thanks.