# ngawidev/netstream architecture

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

- Interactive diagram: https://gitdiagram.com/ngawidev/netstream
- Repository: https://github.com/ngawidev/netstream

## Overview

NetStream is a dependency-light PHP HTTP client built on PHP streams. Callers use the static facade or a reusable Client; each creates or configures a PendingRequest that builds and executes a request, then returns a Response. The request layer supports documented options including retries, redirects, TLS/proxy settings, multipart uploads, downloads, limits and debugging. CookieJar enables persistent cookie matching across requests. The sampled code supports the core wiring shown; other capabilities are included at the documented request-options level.

Main entry points: [`src/PendingRequest.php`](https://github.com/ngawidev/netstream/blob/main/src/PendingRequest.php) (Request builder), [`src/Response.php`](https://github.com/ngawidev/netstream/blob/main/src/Response.php) (Response object), [`src/NetStream.php`](https://github.com/ngawidev/netstream/blob/main/src/NetStream.php) (Static facade), [`src/Client.php`](https://github.com/ngawidev/netstream/blob/main/src/Client.php) (Reusable client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Client entry points"]
  node_facade["Static facade<br/>[NetStream.php]"]
  node_client["Reusable client<br/>[Client.php]"]
end

subgraph group_request["Request execution"]
  node_pending["Request builder<br/>[PendingRequest.php]"]
  node_request_options["Request options<br/>[PendingRequest.php]"]
  node_transport["PHP stream transport<br/>[PendingRequest.php]"]
end

subgraph group_state["Session state"]
  node_cookie_jar[("Cookie jar<br/>[CookieJar.php]")]
end

subgraph group_result["Response handling"]
  node_response["Response object<br/>[Response.php]"]
  node_connection_error["Connection errors"]
  node_request_error["Request errors"]
end

node_caller(("Application caller"))
node_http_service(("HTTP service"))

node_caller -->|"calls"| node_facade
node_caller -->|"configures"| node_client
node_facade -->|"creates or calls"| node_client
node_facade -->|"configures"| node_pending
node_client -->|"creates and configures"| node_pending
node_pending -->|"builds"| node_request_options
node_pending -->|"loads and stores cookies"| node_cookie_jar
node_pending -->|"executes"| node_transport
node_transport -->|"sends request"| node_http_service
node_http_service -->|"returns response"| node_transport
node_transport -->|"constructs"| node_response
node_transport -->|"raises"| node_connection_error
node_response -->|"returns"| node_caller
node_response -->|"parses cookie lines"| node_cookie_jar
node_response -->|"throws on failure"| node_request_error

click node_facade "https://github.com/ngawidev/netstream/blob/main/src/NetStream.php"
click node_client "https://github.com/ngawidev/netstream/blob/main/src/Client.php"
click node_pending "https://github.com/ngawidev/netstream/blob/main/src/PendingRequest.php"
click node_request_options "https://github.com/ngawidev/netstream/blob/main/src/PendingRequest.php"
click node_transport "https://github.com/ngawidev/netstream/blob/main/src/PendingRequest.php"
click node_cookie_jar "https://github.com/ngawidev/netstream/blob/main/src/CookieJar.php"
click node_response "https://github.com/ngawidev/netstream/blob/main/src/Response.php"
click node_connection_error "https://github.com/ngawidev/netstream/blob/main/src/Exceptions/ConnectionException.php"
click node_request_error "https://github.com/ngawidev/netstream/blob/main/src/Exceptions/RequestException.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_facade,node_client toneBlue
class node_pending,node_request_options,node_transport toneAmber
class node_cookie_jar toneMint
class node_response,node_connection_error,node_request_error toneRose
class node_caller,node_http_service toneIndigo
```

## Components

### Client entry points

- [Static facade](https://github.com/ngawidev/netstream/blob/main/src/NetStream.php): `src/NetStream.php`
- [Reusable client](https://github.com/ngawidev/netstream/blob/main/src/Client.php): `src/Client.php`

### Request execution

- [Request builder](https://github.com/ngawidev/netstream/blob/main/src/PendingRequest.php): `src/PendingRequest.php`
- [Request options](https://github.com/ngawidev/netstream/blob/main/src/PendingRequest.php): `src/PendingRequest.php`
- [PHP stream transport](https://github.com/ngawidev/netstream/blob/main/src/PendingRequest.php): `src/PendingRequest.php`

### Session state

- [Cookie jar](https://github.com/ngawidev/netstream/blob/main/src/CookieJar.php): `src/CookieJar.php`

### Response handling

- [Response object](https://github.com/ngawidev/netstream/blob/main/src/Response.php): `src/Response.php`
- [Connection errors](https://github.com/ngawidev/netstream/blob/main/src/Exceptions/ConnectionException.php): `src/Exceptions/ConnectionException.php`
- [Request errors](https://github.com/ngawidev/netstream/blob/main/src/Exceptions/RequestException.php): `src/Exceptions/RequestException.php`

### Other components

- **Application caller**
- **HTTP service**

## Connections

- Application caller → Static facade: calls
- Application caller → Reusable client: configures
- Static facade → Reusable client: creates or calls
- Static facade → Request builder: configures
- Reusable client → Request builder: creates and configures
- Request builder → Request options: builds
- Request builder → Cookie jar: loads and stores cookies
- Request builder → PHP stream transport: executes
- PHP stream transport → HTTP service: sends request
- HTTP service → PHP stream transport: returns response
- PHP stream transport → Response object: constructs
- PHP stream transport → Connection errors: raises
- Response object → Application caller: returns
- Response object → Cookie jar: parses cookie lines
- Response object → Request errors: throws on failure