> For the complete documentation index, see [llms.txt](https://quantumphp.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://quantumphp.gitbook.io/docs/packages/httpclient/overview.md). # Overview The HttpClient package gives Quantum a small native cURL wrapper for outbound HTTP calls. Use it when you want to: * send one HTTP request and inspect its response body, headers, cookies, or cURL info * batch multiple requests through native multi-cURL * keep request setup in Quantum code without talking to raw cURL resources This package is intentionally small. It does not add retries, middleware, authentication helpers, or response object mapping. You work with one `HttpClient` facade backed by Quantum-owned cURL adapters. ## Package shape The package is built from these pieces: * `Quantum\HttpClient\HttpClient` is the runtime wrapper * `Quantum\HttpClient\Factories\HttpClientFactory` creates fresh request facades * `httpRequest()`, `httpMultiRequest()`, and `httpAsyncMultiRequest()` are helper shortcuts * `Quantum\HttpClient\Exceptions\HttpClientException` reports package-specific misuse such as starting before creating a request * `Quantum\HttpClient\Enums\ExceptionMessages` defines local message constants ## Request modes The package supports three modes. ### Single request `createRequest($url)` creates a native `CurlAdapter`, stores the URL, and lets you configure the request through `HttpClient` methods plus supported adapter passthrough methods. This is the only mode that supports: * `setMethod()` * `setData()` * `getRequestHeaders()` * `getResponseHeaders()` * `getResponseCookies()` * `getResponseBody()` * `info()` * `url()` ### Multi request `createMultiRequest()` creates a native `MultiCurlAdapter` and registers a completion callback that collects each finished response into the package's internal response store. Use this when you want to queue several requests and read the aggregated responses after `start()` finishes. ### Async multi request `createAsyncMultiRequest($success, $error)` creates a native `MultiCurlAdapter`, wires your success and error callbacks, and also keeps Quantum's internal response and error stores populated. Use this when your application wants callback handling while still allowing later inspection through `getResponse()` and `getErrors()`. ## Supported single-request methods `setMethod()` only accepts these values: * `GET` * `POST` * `PUT` * `PATCH` * `DELETE` Any other method triggers `HttpClientException::requestMethodNotAvailable(...)`. The list is also available as `HttpClient::METHODS`. You can read back what you set with `getMethod()` and `getData()`, get the underlying adapter with `getAdapter()`, and ask `isMultiRequest()` which kind of request the client holds. ## Response model Responses are stored in three sections: * `headers` * `cookies` * `body` Headers are normalized to lowercase before storage, so `Content-Type` becomes `content-type` when you read it back. The `body` is decoded for you: * when the `Content-Type` contains `json` and the body is valid JSON, it is the result of `json_decode()`, so an object (`stdClass`), not an array * when the `Content-Type` contains `xml` and the body is valid XML, it is a `SimpleXMLElement` * a body sent with `Content-Encoding: gzip` is decompressed first * in every other case, including invalid JSON or XML, it is the raw string For a single request, `getResponse()` returns one response array. For multi requests, `getResponse()` returns a map keyed by curl request ID. ## Important constraints * You must call one of the `create...Request()` methods before calling `start()` or any adapter passthrough method. * Single-request inspection methods are not available for multi-request adapters. * `setData()` only affects the single-request `start()` path. * Request headers are only mirrored into `getRequestHeaders()` when you set them through proxied `setHeader()` or `setHeaders()` calls. * Reusing one `HttpClient` instance across multiple requests keeps prior wrapper state unless you overwrite it. That includes the current method, pending data, tracked request headers, and collected response/error arrays. * Adapter passthrough is intentionally limited to supported adapter methods such as `setHeader()`, `setHeaders()`, `setOpt()`, `setOpts()`, `addGet()`, and `addPost()`. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://quantumphp.gitbook.io/docs/packages/httpclient/overview.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.