Guzzle Mock Handler Laravel Package

Getting Started

Start by installing the package via Composer: composer require --dev tomb1n0/guzzle-mock-handler. It provides a custom Guzzle handler stack compatible with PHPUnit tests—ideal for mocking HTTP responses without relying on external services. The first use case is typically mocking API client calls in unit tests: inject the mock handler into your Guzzle client, define expected requests/responses via GuzzleHttp\MockHandler::append(), and assert interactions using MockHandler::getInfo() or custom assertions.

Implementation Patterns

• Unit Testing HTTP Clients: Wrap your API clients in test doubles using MockHandler, prepending it to your client’s handler stack. Use append() to queue responses matching expected requests.
• Request-Response Pairing: Structure mocks using Request and Response instances (e.g., new Response(200, [], json_encode($data))) to simulate real endpoints precisely.
• Testing Retry Logic: Simulate failures (e.g., 500 errors) followed by successes to verify retry behavior by appending multiple responses in sequence.
• Integration with Guzzle Middleware: Though the handler itself is low-level, you can combine it with middleware (e.g., for logging or timing) by stacking handlers properly.
• Asserting Request Details: Use MockHandler::getLastRequest() (or track in tests) to inspect headers, body, or URI of outgoing requests.

Gotchas and Tips

• Handler Stack Order: Ensure the mock handler is prepended to the handler stack (e.g., HandlerStack::create($mockHandler)), otherwise other handlers may interfere.
• No Real Network Calls: The mock handler only returns pre-defined responses—ensure your test suite isn’t accidentally making real requests (use assertNotSame or断言 to verify no HTTP client leaks to production).
• Per-Test Cleanup: MockHandler isn’t state-resetting automatically; initialize it fresh per test case to avoid stale responses in parallel test runs.
• Limited Diagnostics: Unlike tools like mockery or phpspec, it doesn’t provide rich mocking DSL—combine with PHPUnit assertions for clarity.
• Extension via Handler Wrapping: For advanced needs, wrap MockHandler with Middleware::mock() or create custom handler wrappers to inject request validation logic.