# guzzle/guzzle architecture

> Architecture diagram of the GitHub repository guzzle/guzzle, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/guzzle/guzzle
- Repository: https://github.com/guzzle/guzzle

## Overview

Guzzle is a PHP HTTP client. The principal workflow is: an application creates a client and issues a PSR-7 request; client configuration and middleware prepare or augment it; a selected transport performs the exchange and returns a response or transfer error. Documented capabilities include sync/async calls, streaming, cookies, authentication, redirects, retries, pooling, and transport abstraction. Some feature modules were not excerpted, so their connections are shown as unverified where appropriate.

Main entry points: [`src/Client.php`](https://github.com/guzzle/guzzle/blob/8.3/src/Client.php) (HTTP Client), [`src/HandlerStack.php`](https://github.com/guzzle/guzzle/blob/8.3/src/HandlerStack.php) (Handler Stack), [`src/Utils.php`](https://github.com/guzzle/guzzle/blob/8.3/src/Utils.php) (Transport Selection), [`src/Cookie/CookieJar.php`](https://github.com/guzzle/guzzle/blob/8.3/src/Cookie/CookieJar.php) (Cookie Jar)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client API"]
  node_client["HTTP Client<br/>[Client.php]"]
  node_client_api["Client Interface"]
  node_pool["Request Pool<br/>[Pool.php]"]
end

subgraph group_middleware["Request Behavior"]
  node_handler_stack["Handler Stack<br/>[HandlerStack.php]"]
  node_auth["Authentication<br/>[AuthMiddleware.php]"]
  node_prepare_body["Body Preparation"]
  node_redirect["Redirect Handling"]
  node_retry["Retry Handling"]
end

subgraph group_transport["HTTP Transports"]
  node_transport_select["Transport Selection<br/>[Utils.php]"]
  node_curl["cURL Transport<br/>[CurlHandler.php]"]
  node_curl_multi["Async cURL"]
  node_streams["PHP Streams<br/>[StreamHandler.php]"]
end

subgraph group_state["Transfer State"]
  node_cookie_jar["Cookie Jar<br/>[CookieJar.php]"]
  node_set_cookie["Cookie Parsing<br/>[SetCookie.php]"]
  node_file_cookie["File Cookie Jar<br/>[FileCookieJar.php]"]
  node_session_cookie["Session Cookie Jar"]
  node_transfer_sharing["Transport Sharing"]
end

subgraph group_errors["Errors and Diagnostics"]
  node_request_errors["Request Errors"]
  node_response_errors["Response Errors"]
end

node_application(("Application"))
node_remote(("HTTP Service"))

node_application -->|"creates client"| node_client
node_application -->|"issues requests"| node_client_api
node_client -->|"configures handlers"| node_handler_stack
node_client -->|"uses cookies"| node_cookie_jar
node_client -->|"implements"| node_client_api
node_handler_stack -.->|"may compose"| node_auth
node_handler_stack -.->|"may compose"| node_prepare_body
node_handler_stack -.->|"may compose"| node_redirect
node_handler_stack -.->|"may compose"| node_retry
node_client -.->|"supports pooled requests"| node_pool
node_cookie_jar -->|"parses cookies"| node_set_cookie
node_file_cookie -->|"extends jar behavior"| node_cookie_jar
node_session_cookie -->|"extends jar behavior"| node_cookie_jar
node_client -->|"selects handler"| node_transport_select
node_transport_select -->|"chooses async cURL"| node_curl_multi
node_transport_select -->|"chooses cURL"| node_curl
node_transport_select -->|"chooses streams"| node_streams
node_curl -->|"sends HTTP"| node_remote
node_curl_multi -.->|"sends concurrent HTTP"| node_remote
node_streams -.->|"sends HTTP"| node_remote
node_curl -->|"configures sharing"| node_transfer_sharing
node_curl_multi -->|"configures sharing"| node_transfer_sharing
node_remote -->|"returns response"| node_client
node_request_errors -->|"creates response errors"| node_response_errors

click node_client "https://github.com/guzzle/guzzle/blob/8.3/src/Client.php"
click node_client_api "https://github.com/guzzle/guzzle/blob/8.3/src/ClientInterface.php"
click node_handler_stack "https://github.com/guzzle/guzzle/blob/8.3/src/HandlerStack.php"
click node_auth "https://github.com/guzzle/guzzle/blob/8.3/src/AuthMiddleware.php"
click node_prepare_body "https://github.com/guzzle/guzzle/blob/8.3/src/PrepareBodyMiddleware.php"
click node_redirect "https://github.com/guzzle/guzzle/blob/8.3/src/RedirectMiddleware.php"
click node_retry "https://github.com/guzzle/guzzle/blob/8.3/src/RetryMiddleware.php"
click node_pool "https://github.com/guzzle/guzzle/blob/8.3/src/Pool.php"
click node_cookie_jar "https://github.com/guzzle/guzzle/blob/8.3/src/Cookie/CookieJar.php"
click node_set_cookie "https://github.com/guzzle/guzzle/blob/8.3/src/Cookie/SetCookie.php"
click node_file_cookie "https://github.com/guzzle/guzzle/blob/8.3/src/Cookie/FileCookieJar.php"
click node_session_cookie "https://github.com/guzzle/guzzle/blob/8.3/src/Cookie/SessionCookieJar.php"
click node_transport_select "https://github.com/guzzle/guzzle/blob/8.3/src/Utils.php"
click node_curl "https://github.com/guzzle/guzzle/blob/8.3/src/Handler/CurlHandler.php"
click node_curl_multi "https://github.com/guzzle/guzzle/blob/8.3/src/Handler/CurlMultiHandler.php"
click node_streams "https://github.com/guzzle/guzzle/blob/8.3/src/Handler/StreamHandler.php"
click node_request_errors "https://github.com/guzzle/guzzle/blob/8.3/src/Exception/RequestException.php"
click node_response_errors "https://github.com/guzzle/guzzle/blob/8.3/src/Exception/ResponseException.php"
click node_transfer_sharing "https://github.com/guzzle/guzzle/blob/8.3/src/Handler/CurlShareHandleState.php"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_client,node_client_api,node_pool toneBlue
class node_handler_stack,node_auth,node_prepare_body,node_redirect,node_retry toneAmber
class node_transport_select,node_curl,node_curl_multi,node_streams toneMint
class node_cookie_jar,node_set_cookie,node_file_cookie,node_session_cookie,node_transfer_sharing toneRose
class node_request_errors,node_response_errors,node_application,node_remote toneIndigo
```

## Components

### Client API

- [HTTP Client](https://github.com/guzzle/guzzle/blob/8.3/src/Client.php): `src/Client.php`
- [Client Interface](https://github.com/guzzle/guzzle/blob/8.3/src/ClientInterface.php): `src/ClientInterface.php`
- [Request Pool](https://github.com/guzzle/guzzle/blob/8.3/src/Pool.php): `src/Pool.php`

### Request Behavior

- [Handler Stack](https://github.com/guzzle/guzzle/blob/8.3/src/HandlerStack.php): `src/HandlerStack.php`
- [Authentication](https://github.com/guzzle/guzzle/blob/8.3/src/AuthMiddleware.php): `src/AuthMiddleware.php`
- [Body Preparation](https://github.com/guzzle/guzzle/blob/8.3/src/PrepareBodyMiddleware.php): `src/PrepareBodyMiddleware.php`
- [Redirect Handling](https://github.com/guzzle/guzzle/blob/8.3/src/RedirectMiddleware.php): `src/RedirectMiddleware.php`
- [Retry Handling](https://github.com/guzzle/guzzle/blob/8.3/src/RetryMiddleware.php): `src/RetryMiddleware.php`

### HTTP Transports

- [Transport Selection](https://github.com/guzzle/guzzle/blob/8.3/src/Utils.php): `src/Utils.php`
- [cURL Transport](https://github.com/guzzle/guzzle/blob/8.3/src/Handler/CurlHandler.php): `src/Handler/CurlHandler.php`
- [Async cURL](https://github.com/guzzle/guzzle/blob/8.3/src/Handler/CurlMultiHandler.php): `src/Handler/CurlMultiHandler.php`
- [PHP Streams](https://github.com/guzzle/guzzle/blob/8.3/src/Handler/StreamHandler.php): `src/Handler/StreamHandler.php`

### Transfer State

- [Cookie Jar](https://github.com/guzzle/guzzle/blob/8.3/src/Cookie/CookieJar.php): `src/Cookie/CookieJar.php`
- [Cookie Parsing](https://github.com/guzzle/guzzle/blob/8.3/src/Cookie/SetCookie.php): `src/Cookie/SetCookie.php`
- [File Cookie Jar](https://github.com/guzzle/guzzle/blob/8.3/src/Cookie/FileCookieJar.php): `src/Cookie/FileCookieJar.php`
- [Session Cookie Jar](https://github.com/guzzle/guzzle/blob/8.3/src/Cookie/SessionCookieJar.php): `src/Cookie/SessionCookieJar.php`
- [Transport Sharing](https://github.com/guzzle/guzzle/blob/8.3/src/Handler/CurlShareHandleState.php): `src/Handler/CurlShareHandleState.php`

### Errors and Diagnostics

- [Request Errors](https://github.com/guzzle/guzzle/blob/8.3/src/Exception/RequestException.php): `src/Exception/RequestException.php`
- [Response Errors](https://github.com/guzzle/guzzle/blob/8.3/src/Exception/ResponseException.php): `src/Exception/ResponseException.php`

### Other components

- **Application**
- **HTTP Service**

## Connections

- Application → HTTP Client: creates client (evidence: `README.md`)
- Application → Client Interface: issues requests (evidence: `README.md`)
- HTTP Client → Handler Stack: configures handlers (evidence: `src/Client.php`)
- HTTP Client → Cookie Jar: uses cookies (evidence: `src/Client.php`)
- HTTP Client → Client Interface: implements (evidence: `src/Client.php`)
- Handler Stack → Authentication: may compose
- Handler Stack → Body Preparation: may compose
- Handler Stack → Redirect Handling: may compose
- Handler Stack → Retry Handling: may compose
- HTTP Client → Request Pool: supports pooled requests
- Cookie Jar → Cookie Parsing: parses cookies (evidence: `src/Cookie/CookieJar.php`)
- File Cookie Jar → Cookie Jar: extends jar behavior (evidence: `src/Cookie/FileCookieJar.php`)
- Session Cookie Jar → Cookie Jar: extends jar behavior (evidence: `src/Cookie/SessionCookieJar.php`)
- HTTP Client → Transport Selection: selects handler (evidence: `src/Client.php`)
- Transport Selection → Async cURL: chooses async cURL (evidence: `src/Utils.php`)
- Transport Selection → cURL Transport: chooses cURL (evidence: `src/Utils.php`)
- Transport Selection → PHP Streams: chooses streams (evidence: `src/Utils.php`)
- cURL Transport → HTTP Service: sends HTTP (evidence: `src/Handler/CurlHandler.php`)
- Async cURL → HTTP Service: sends concurrent HTTP
- PHP Streams → HTTP Service: sends HTTP
- cURL Transport → Transport Sharing: configures sharing (evidence: `src/Handler/CurlHandler.php`)
- Async cURL → Transport Sharing: configures sharing (evidence: `src/Handler/CurlMultiHandler.php`)
- HTTP Service → HTTP Client: returns response (evidence: `README.md`)
- Request Errors → Response Errors: creates response errors (evidence: `src/Exception/RequestException.php`)
