How can I create a custom middleware for Guzzle?

Guzzle is a PHP HTTP client that simplifies the process of making HTTP requests and integrating with web services. Creating custom middleware in Guzzle allows you to tap into the request/response lifecycle to modify requests, handle responses, or add logging, caching, authentication, and other features.

To create a custom middleware in Guzzle, you need to define a callable that accepts a handler. This handler is a function that will eventually send the HTTP request. Your middleware can perform actions before or after this handler is invoked.

Here's a step-by-step guide on how to create a custom middleware:

1. Define the Middleware: Your middleware should be a callable that returns a function with the signature function (RequestInterface $request, array $options). Inside this function, you can do whatever you need with the $request or $options, and then you must pass them to the $handler.

2. Add the Middleware to the Handler Stack: Guzzle uses a HandlerStack to manage middleware. You need to push your middleware onto this stack before you create the client.

3. Create the Client with the Handler Stack: When you instantiate the Guzzle client, pass the modified handler stack as an option.

Here's an example of a simple custom middleware that adds a custom header to every request:

use GuzzleHttp\HandlerStack;
use GuzzleHttp\Middleware;
use GuzzleHttp\Client;
use Psr\Http\Message\RequestInterface;

// Step 1: Define the middleware
$customMiddleware = function (callable $handler) {
    return function (RequestInterface $request, array $options) use ($handler) {
        // Add a custom header to the request
        $request = $request->withHeader('X-Custom-Header', 'MyValue');

        // Pass the request to the next handler
        return $handler($request, $options);
    };
};

// Step 2: Add the middleware to the HandlerStack
$stack = HandlerStack::create();
$stack->push(Middleware::mapRequest($customMiddleware), 'custom_header');

// Step 3: Create the Client with the HandlerStack
$client = new Client(['handler' => $stack]);

// Now, when you send a request, the custom header will be included
$response = $client->request('GET', 'https://example.com');

// You can verify that the custom header is being sent by looking at the request object
echo $response->getHeaderLine('X-Custom-Header');

In the above example, the $customMiddleware is a closure that wraps the $handler and modifies the $request by adding a custom header. The Middleware::mapRequest method is a helper that provides a convenient way to modify the request before it's sent.

You can also handle responses by using the Middleware::mapResponse method or handle exceptions by using the Middleware::tap method in a similar fashion.

The Guzzle documentation provides more information on creating middleware and the different types of middleware you can create: http://docs.guzzlephp.org/en/stable/handlers-and-middleware.html

Remember to test your middleware thoroughly to ensure it behaves correctly in all scenarios, including error handling and asynchronous requests if your application uses them.