How platformatic/php-node works
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/