[10.x] Add global middleware to Http client

[timacdonald]

💡 Updated!

This PR allows an application to add Guzzle middleware that is applied to every request made via the Http client. It also introduces some nicer named methods to add request / response only middleware.

Read more about Guzzle middleware in their docs.

As an example, an application may globally set a User-Agent header, to be a good citizen of the Internet. To do this, you may add a global "request" middleware:

// In a service provider...

use Illuminate\Support\Facades\Http;

Http::globalRequestMiddleware(
    fn ($request) => $request->withHeader('User-Agent', 'Laravel Framework/1.0')
);

This will mean that every outgoing request will now have the User-Agent: Laravel Framework/1.0 header.

Here is another example, showing the addition of a global "response" middleware.

// In a service provider...

use Illuminate\Support\Facades\Http;

Http::globalResponseMiddleware(
    fn ($response) => $response->withHeader('X-Finished-At', now()->toDateTimeString())
);

It is also possible, of course, to add a complete middleware that wraps both the request and response cycle. As an example, the following middleware will add a response header including the duration of the request in milliseconds. The value may also be logged or recorded elsewhere.

// In a service provider...

use Illuminate\Support\Facades\Http;

Http::globalMiddleware(function ($handler) {
    return function ($request, $options) use ($handler) {
        $startedAt = now();

        return $handler($request, $options)
            ->then(fn ($response) => $response->withHeader(
                'X-Duration', $startedAt->diffInMilliseconds(now())
            ));
    };
});

Something like the above would also be possible via the on_stats Guzzle option.

The global middleware is also useful for logging and inspection of outgoing requests or incoming responses, although this is also possible by listening to events, but now we have a unified way of doing this.

// In a service provider...

use RuntimeException;
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\Log;

Http::globalRequestMiddleware(function ($request) {
    if ($request->getUri()->getScheme() !== 'https') {
        throw new RuntimeException('Outgoing HTTP connections must use HTTPS.');
    }

    Log::info('Sending a HTTP request', ['url' => (string) $request->getUri()]);

    return $request;
});

I've also introduced named middleware methods for the request / response middleware to the PendingRequest class. These make adding middleware feel more at home in Laravel, IMO, when compared to having to reference the GuzzleHttp\Middleware class directly.

Here is a before and after of using the new named methods for a "request" middleware:

- use GuzzleHttp\Middleware;
use Illuminate\Support\Facades\Http;
 
- $response = Http::withMiddleware(Middleware::mapRequest(function ($request) {
+ $response = Http::withRequestMiddleware(function ($request) {
    return $request->withHeader('X-Example', 'Value');
- }))->get('http://example.com');
+ })->get('http://example.com');

You can see the currently documented way in the screenshot below. I feel these named methods greatly streamline the user-facing API.

Here is the full API for adding middleware to Http requests after this PR:

// Global middleware...

Http::globalMiddleware(function ($handler) {
    // ...
});

// Global request middleware...

Http::globalRequestMiddleware(function ($request) {
    // ...
});

// Global response middleware...

Http::globalResponseMiddleware(function ($response) {
    // ...
});

// One-time middleware...

Http::withMiddleware(function ($handler) {
    // ...
})->get(/* ... */);

// One-time request middleware...

Http::withRequestMiddleware(function ($handler) {
    // ...
})->get(/* ... */);

// One-time response middleware...

Http::withResponseMiddleware(function ($handler) {
    // ...
})->get(/* ... */);

Similar PRs:

• [10.x] Add global default options feature to HTTP client. #46637
• [8.x] Add Http::configure() method #40332