Some extra explanation is probably needed here.

I haven't seen anything insymfony/symfony#30413 relating to the BrowserKit component and the documentation for the Browser component states you must implement thedoRequest(Request $request): Response method, meaning you'd have to:

• Convert$request object to$httpClient->request($method, $url, $options)
• ConvertSymfony\Contracts\HttpClient\ResponseInterface toSymfony\Component\HttpFoundation\Response

This is non-trivial, and definitely not seamless. Perhaps an idea would be to add a static helper method (likeSymfony\Component\HttpClient\HttpOptions::fromFoundationRequest($request)) and add an example in this section.

(I know you've mentioned you're also improving BrowserKit, and may have already addressed this - if so ignore this!)

EDIT I just read Fabien's slides and saw that there's going to be a newSymfony\Component\BrowserKit\BrowserClient(HttpClientInterface $client) class. Once that's merged in it would still be a good idea to show an example of that here 🙂

Perfectly explained! We need to wait for the merge of the BrowserKit improvements and then we'll add a mention here. Thanks.

Should we add some explanation of what the closure needs to return?

This is not the only requirement. Curl has to be compiled with libnghttp2 as well. Not sure if we should mention that though.
Basically, HTTP2 support is automatically enabled if your environment supports it.

This is not exactly true, is it?
We send the request as soon as you run the $response-getStatusCode().