# platformatic/php-node architecture

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

- Interactive diagram: https://gitdiagram.com/platformatic/php-node
- Repository: https://github.com/platformatic/php-node

## Overview

##### Project Type and Purpose
- This is an open-source Node.js library (`@platformatic/php-node`) that embeds a PHP runtime into a Node.js process. It exposes a JavaScript API (`Php`, `Request`, `Response`, `Rewriter`, `Headers`) while under the hood leveraging Rust crates (via N-API) to host and drive the PHP interpreter with zero network hops.

##### Core File Structure Analysis
- Top-level JS wrapper:
- `index.js` / `index.d.ts` + `package.json` — defines the public API and loads the native addon.
- `demo/` — example of using the library in a Node.js server.
- Native addon code in Rust, organized under `crates/`:
- `crates/php_node` — N-API bindings exposing `Php`, `Request`, `Response`, `Headers`, `Rewriter` to JS.
- `crates/php` — embedding the PHP engine, managing lifecycles, SAPI interactions, scopes, exceptions.
- `crates/lang_handler` — request rewriting logic (conditional matchers + rewriters).
- Packaging output:
- `npm/…` — prebuilt binaries for multiple OS/arch targets.
- Tests:
- `__test__/*.mjs` — JS tests against the public API.
- Rust tests under `crates/*/src/test.rs`.

1. **JavaScript Layer**
- User code
- `Php`, `Request`, `Response`, `Rewriter`, `Headers` classes
2. **Node.js Worker Pool**
- Internal worker threads (via NodePlatform) to offload blocking PHP work
3. **Native Addon (Rust N-API module)**
- `crates/php_node`
4. **Lang Handler**
- `crates/lang_handler` implementing rewrite rules (conditions + rewriters)
5. **PHP Embed Layer**
- `crates/php` — PHP SAPI embed, request context, exception handling, PHP stdlib calls
6. **Filesystem / Docroot**
- `.php` files on disk
7. **External Dependencies**
- System libs (`libssl`, `libcurl`, `libxml2`, etc.)

1. JS code calls `new Php(config)` → N-API init → spawns worker(s).
2. JS calls `php.handleRequest(request)` → enqueued to worker.
3. Worker thread invokes N-API entry point in `crates/php_node`.
4. In `php_node`:
- Construct internal Rust `Request`/`Response` structures.
- If configured, pass request through **Lang Handler** for rewriting.
5. Forward to **PHP Embed Layer**:
- Rust request → PHP SAPI request context.
- Execute PHP files under `docroot`.
- Gather status, headers, body, and any logs.
6. Return `Response` struct → back through N-API → worker → Promise resolves in JS.
7. JS user-land receives and inspects `Response`.

c. Architectural Patterns & Principles
- **Language Bridging**: JS ↔ Rust ↔ C (PHP embed).
- **Worker Pool**: isolates blocking operations from main thread.
- **Modular Separation**:
- `php_node` for JS binding
- `lang_handler` for HTTP rewriting logic
- `php` for PHP engine lifecycle
- **Prebuilt Binaries**: packaging per OS/arch under `npm/`.

d. Key Technologies & Frameworks
- Node.js N-API for native addons
- Rust crates + Cargo for native code
- Embedded PHP SAPI (C API)
- Regular expressions for rewrite logic
- GitHub Actions for CI (`.github/workflows`)
- npm packaging with OS-specific binaries

##### Essential Details to Capture
- Separation between JS caller and native addon
- Worker pool isolating PHP work
- Rewriter module’s position between request intake and PHP dispatch
- Two distinct Rust crates for N-API bindings vs. PHP engine
- Prebuilt binary packaging per target in `npm/`

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% JavaScript Layer
    subgraph "JavaScript Layer"
        direction TB
        IndexJS["index.js"]:::js
        IndexDTS["index.d.ts"]:::js
        PackageJSON["package.json"]:::js
    end

    %% Demo / Example Usage
    subgraph "Demo / Example Usage"
        direction TB
        DemoServer["demo/server.js"]:::demo
        DemoHTML["demo/index.html"]:::demo
        DemoPHP["demo/index.php"]:::demo
        DemoPkg["demo/package.json"]:::demo
    end

    %% Worker Pool
    Worker["Worker Pool\n(node worker threads)"]:::worker

    %% Native Addon
    subgraph "Native Addon (Rust N-API Bindings)"
        direction TB
        NativeDir["crates/php_node/"]:::rust
    end

    %% Language Handler
    subgraph "Lang Handler (HTTP Rewriting)"
        direction TB
        LangDir["crates/lang_handler/"]:::rust
    end

    %% PHP Embed Layer
    subgraph "PHP Embed Layer"
        direction TB
        PHPDir["crates/php/"]:::php
    end

    %% Filesystem & External
    FS["Filesystem (docroot .php files)"]:::fs
    Ext["External System Libs\nlibssl, libcurl, libxml2"]:::ext

    %% Data Flow
    DemoServer -->|"uses API"| IndexJS
    IndexJS -->|"new Php(config)\n→ N-API init"| Worker
    Worker -->|"invoke N-API entry"| NativeDir
    NativeDir -->|"request struct\n→ rewrite"| LangDir
    LangDir -->|"apply rewrite rules"| PHPDir
    PHPDir -->|"load .php scripts"| FS
    PHPDir -->|"uses C API"| Ext
    PHPDir -->|"build Response"| NativeDir
    NativeDir -->|"return via N-API"| Worker
    Worker -->|"Promise resolves"| IndexJS

    %% Click Events
    click IndexJS "https://github.com/platformatic/php-node/blob/main/index.js"
    click IndexDTS "https://github.com/platformatic/php-node/blob/main/index.d.ts"
    click PackageJSON "https://github.com/platformatic/php-node/blob/main/package.json"
    click DemoServer "https://github.com/platformatic/php-node/blob/main/demo/server.js"
    click DemoHTML "https://github.com/platformatic/php-node/blob/main/demo/index.html"
    click DemoPHP "https://github.com/platformatic/php-node/blob/main/demo/index.php"
    click DemoPkg "https://github.com/platformatic/php-node/blob/main/demo/package.json"
    click NativeDir "https://github.com/platformatic/php-node/tree/main/crates/php_node/"
    click LangDir "https://github.com/platformatic/php-node/tree/main/crates/lang_handler/"
    click PHPDir "https://github.com/platformatic/php-node/tree/main/crates/php/"
    click FS "https://github.com/platformatic/php-node/tree/main/./"
    click Ext "https://github.com/platformatic/php-node/tree/main/./"

    %% Styles
    classDef js fill:#D0E6FF,stroke:#0366d6,color:#0366d6;
    classDef demo fill:#E8F5E9,stroke:#388E3C,color:#388E3C;
    classDef worker fill:#FFF3E0,stroke:#FB8C00,color:#E65100;
    classDef rust fill:#E8EAF6,stroke:#3F51B5,color:#303F9F;
    classDef php fill:#FFF3E0,stroke:#F57C00,color:#E65100;
    classDef fs fill:#F5F5F5,stroke:#9E9E9E,color:#616161;
    classDef ext fill:#F5F5F5,stroke:#9E9E9E,color:#616161;
```
