Weave Code
Guzzle Laravel Package
guzzlehttp/guzzle
Guzzle is a PHP HTTP client that makes sending HTTP requests simple and integrating with web services trivial. It supports sync and async requests, PSR-7 and PSR-18 interfaces, streaming uploads and downloads, middleware, and abstracts away the underlying transport.
Guzzle, an extensible PHP HTTP client
Frequently asked questions about Guzzle
- How do I install Guzzle in a Laravel application?
- Install it with Composer by running composer require guzzlehttp/guzzle from your project root. Laravel's own HTTP wrapper already depends on Guzzle, so most applications get it transitively, but requiring it explicitly pins the version you actually test against. Once installed you can resolve GuzzleHttp\Client from the container or instantiate it directly, and optionally bind a preconfigured client as a singleton in a service provider.
- Does Laravel already ship with Guzzle, or do I need to require it myself?
- Laravel's Illuminate\Http\Client is a thin, fluent wrapper around Guzzle, so a Guzzle version is normally already present in vendor once the framework is installed. You only need an explicit require when you want to call GuzzleHttp\Client directly, use middleware, or control the version constraint yourself. Keeping it explicit avoids surprise breakage when a framework upgrade shifts the transitive constraint.
- Why does composer require guzzlehttp/guzzle fail with a psr7 version Conflict in Laravel?
- Laravel 10.x through 12.x typically constrain guzzlehttp/guzzle to the 7.x line and guzzlehttp/psr7 to the 2.x line, while newer Guzzle majors move to psr7 3.x and promises 3.x. That creates a two-dimensional conflict: widening only the top-level Guzzle constraint still leaves the PSR-7 major line unresolvable. Run composer why guzzlehttp/psr7 and composer why guzzlehttp/promises to find every package pinning the older majors, then check the framework's own constraints for the specific Laravel minor you are on before planning an override.
- How do I send asynchronous or concurrent HTTP requests with Guzzle in Laravel?
- Use requestAsync, getAsync, or postAsync to get a promise, then settle them together with GuzzleHttp\Promise\Utils::settle or unwrap in a pool. Running requests concurrently is the main reason teams reach for Guzzle directly instead of the Laravel HTTP client, and it is well suited to queue workers and Horizon jobs. In long-running workers, configure max_host_connections and max_total_connections so bursts do not exhaust sockets, and always set an explicit timeout so a stuck upstream cannot hang the worker.
- What is the difference between Guzzle 7 and Guzzle 8, and should I upgrade now?
- Guzzle 8 raises the PHP floor, tightens transitive constraints on psr7 and promises, and carries a set of breaking changes documented in UPGRADING.md. Before upgrading, review that guide in full and audit your dependency tree, because any first-party or vendor package that type-hints PSR-7 v2 types or pins guzzlehttp/psr7 ^2 becomes a resolution blocker. If you are on a stock Laravel 10 to 12 application, staying on the 7.x maintenance line until the framework widens its constraints is usually the lower-risk choice.
- How do I mock Guzzle requests in Laravel tests so I do not hit real APIs?
- Inject a GuzzleHttp\Handler\MockHandler wrapped in a HandlerStack as the client's handler, queue up the responses you expect, and assert on the recorded requests afterwards. The Guzzle docs cover this in Testing Guzzle Clients, including history middleware for inspecting what was sent. If your code goes through the Laravel HTTP client instead, Http::fake is simpler, but mocking at the Guzzle handler level is the reliable option when you use Guzzle directly.
- How do I stream large file uploads and downloads with Guzzle?
- Pass a stream resource or a PSR-7 stream as the body and set the stream option to true, then read the response body incrementally with read calls until eof instead of casting it to a string. Streaming avoids loading entire payloads into memory, which matters for large uploads, exports, and proxy endpoints. Newer Guzzle releases align the stream handler with libcurl semantics, so truncated or malformed chunked responses now raise errors rather than silently returning partial content.
- How do I add retry and logging to Guzzle using middleware?
- Build a HandlerStack, push GuzzleHttp\Middleware::retry with a decision callback, and push a logging middleware such as Middleware::log with a PSR-3 logger. Push order matters because middleware wraps the handler in reverse, so the last pushed middleware runs first on the way out. Keep your retry decision callback explicit about which status codes and exceptions are retryable, since defaults key on exception type and error classification can shift between Guzzle releases.
- Is Guzzle PSR-18 and PSR-7 compliant, and why does that matter in Laravel?
- Yes. Guzzle implements PSR-18 client interfaces and uses PSR-7 for requests, responses, and streams, so it can be swapped for any other compliant client without changing call sites. That matters in Laravel because type-hinting Psr\Http\Message\ResponseInterface rather than GuzzleHttp\Psr7\Response keeps your services portable and testable. Be aware that packages type-hinted against PSR-7 v2 will not resolve cleanly against a v3-based Guzzle install.
- What are the alternatives to Guzzle for HTTP requests in PHP and Laravel?
- The most common options are the Laravel HTTP client for everyday JSON calls, symfony/http-client for a PSR-18 client with strong concurrency and HTTP/2 support, and raw cURL when you need full control. Guzzle remains the de facto standard because of its middleware system, streaming support, and ubiquity in the Composer ecosystem. Many teams use the Laravel client for simple work and drop to Guzzle only when they need async pools, custom handlers, or fine-grained transport control.
Weaver
How can I help you explore Laravel packages today?