# reactphp/stream architecture

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

- Interactive diagram: https://gitdiagram.com/reactphp/stream
- Repository: https://github.com/reactphp/stream

## Overview

##### Main Components
- API Interfaces – Represent the three core interfaces:
○ ReadableStreamInterface
○ WritableStreamInterface
○ DuplexStreamInterface
- Concrete Implementations – Include the classes from the src folder:
○ ReadableResourceStream, WritableResourceStream, DuplexResourceStream
○ ThroughStream and CompositeStream
- Utility Components – Represent supporting classes like Util and any helper methods.
- Example Usage – Although not part of the core library, the “examples” directory should be represented as consumers/demonstrations of how the streams are used.
- Testing – Represent the test suites (unit tests and integration tests) to indicate that a rigorous test harness validates the stream behavior.

##### Relationships and Interactions
- How the abstract interfaces provide a contract for all stream types.
- That concrete classes (e.g., DuplexResourceStream) implement these interfaces and internally delegate to the underlying PHP stream resources.
- Event flow: label events (data, end, error, close, drain, pipe) and show that the streams emit these events which are handled by consumers (or by other streams in the case of pipe() interactions).
- That the ThroughStream optionally accepts a callback to transform data and that CompositeStream composes separate readable and writable streams.
- Dependencies with the ReactPHP EventLoop (external) handling readiness of resources so that writes and reads are processed asynchronously.

##### Key Architectural Patterns/Design Principles
- Interface-based design: Emphasize how the library defines explicit contracts for stream behavior.
- Composition: Show how CompositeStream merges separate stream objects to produce a unified duplex behavior.
- Non-blocking I/O abstraction: Include a note that the library leverages event loops (even if not defined inside the project, it is an essential external integration point).

##### Relevant Technologies and Frameworks
- PHP as the programming language.
- ReactPHP (notably the EventLoop component as well as connectors like react/socket, react/http) for non-blocking asynchronous I/O.
- Testing tools: PHPUnit and PHPStan (the latter making sure type safety is upheld).

##### Additional Details
- An overall view that is structured like layers:
- At the bottom: Integration with the underlying PHP stream resources and the external EventLoop.
- In the middle: The core implementation (interfaces and concrete stream classes).
- At the top: Higher-level usage examples, application integration, and test components.

## Diagram (Mermaid)

```mermaid
flowchart TD

    subgraph "Higher-Level Usage"
        EX["Examples"]:::example
        TS["Tests"]:::test
    end

    subgraph "Core Library"
        subgraph "API Interfaces"
            I1["ReadableStreamInterface"]:::interface
            I2["WritableStreamInterface"]:::interface
            I3["DuplexStreamInterface"]:::interface
        end
        subgraph "Concrete Implementations"
            C1["ReadableResourceStream"]:::concrete
            C2["WritableResourceStream"]:::concrete
            C3["DuplexResourceStream"]:::concrete
            C4["ThroughStream"]:::concrete
            C5["CompositeStream"]:::concrete
        end
        U["Util"]:::utility
    end

    subgraph "External Dependencies"
        E["ReactPHP EventLoop & Modules"]:::external
    end

    %% Implementation relationships
    C1 -->|"implements"| I1
    C2 -->|"implements"| I2
    C3 -->|"implements"| I3
    C4 -->|"implements"| I3
    C5 -->|"implements"| I3

    %% Composite relationship
    C5 -->|"composes"| C1
    C5 -->|"composes"| C2

    %% External non-blocking I/O integration
    E -->|"non-blocking_I/O"| C1
    E -->|"non-blocking_I/O"| C2
    E -->|"non-blocking_I/O"| C3
    E -->|"non-blocking_I/O"| C4
    E -->|"non-blocking_I/O"| C5

    %% Utility usage
    U -->|"supports"| C5

    %% Example usage interactions
    EX -->|"demonstrates_pipe"| C4
    EX -->|"demonstrates_composite"| C5

    %% Testing interactions
    TS -->|"tests_events"| C5
    TS -->|"tests_event_emission"| C4

    %% Styles
    classDef interface fill:#A6CEE3,stroke:#000,stroke-width:2px;
    classDef concrete fill:#B2DF8A,stroke:#000,stroke-width:2px;
    classDef utility fill:#FDBF6F,stroke:#000,stroke-width:2px;
    classDef external fill:#FF9F99,stroke:#000,stroke-width:2px;
    classDef example fill:#CAB2D6,stroke:#000,stroke-width:2px;
    classDef test fill:#FFFF99,stroke:#000,stroke-width:2px;

    %% Click Events
    click I1 "https://github.com/reactphp/stream/blob/3.x/src/ReadableStreamInterface.php"
    click I2 "https://github.com/reactphp/stream/blob/3.x/src/WritableStreamInterface.php"
    click I3 "https://github.com/reactphp/stream/blob/3.x/src/DuplexStreamInterface.php"
    click C1 "https://github.com/reactphp/stream/blob/3.x/src/ReadableResourceStream.php"
    click C2 "https://github.com/reactphp/stream/blob/3.x/src/WritableResourceStream.php"
    click C3 "https://github.com/reactphp/stream/blob/3.x/src/DuplexResourceStream.php"
    click C4 "https://github.com/reactphp/stream/blob/3.x/src/ThroughStream.php"
    click C5 "https://github.com/reactphp/stream/blob/3.x/src/CompositeStream.php"
    click U "https://github.com/reactphp/stream/blob/3.x/src/Util.php"
    click EX "https://github.com/reactphp/stream/tree/3.x/examples/"
    click TS "https://github.com/reactphp/stream/tree/3.x/tests/"
```
