Skip to content

CLAUDE.md

Latest commit

 

History

History
131 lines (96 loc) · 4.52 KB

CLAUDE.md

File metadata and controls

131 lines (96 loc) · 4.52 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

@platformatic/php-node is a Node.js native addon that embeds PHP within the same process as Node.js, enabling seamless communication without network overhead. It's built with Rust using NAPI-RS for safe and performant bindings.

Essential Commands

Development

# Build release version
npm run build

# Build debug version (faster compilation, includes debug symbols)
npm run build:debug

# Run all tests
npm test

# Run specific test file
npx ava __test__/headers.spec.mjs

# Lint JavaScript code  
npm run lint

# Create universal binary (macOS)
npm run universal

# Version bump
npm run version

Rust-specific builds

# Build with proper rpath for linking libphp
RUSTFLAGS="-C link-args=-Wl,-rpath,\$ORIGIN" npm run build

# Run Rust tests
cargo test

# Run binary directly
cargo run

Architecture

Multi-language Structure

  • Rust (/src): Single-crate implementation
    • PHP embedding and SAPI implementation
    • NAPI bindings exposing Rust to Node.js (when napi-support feature is enabled)
    • Binary target for standalone testing (src/main.rs)
    • Library target for NAPI usage (src/lib.rs)
  • JavaScript: Node.js API layer (index.js, index.d.ts)
  • PHP: Embedded runtime via libphp.{so,dylib}

Key Components

  1. PHP Class (index.js): Main entry point for creating PHP environments

    • Manages rewriter rules for URL routing
    • Handles request/response lifecycle
    • Supports both sync and async request handling

  2. Request/Response Model: Web standards-compatible implementation

    • Request class with headers, body, method
    • Response class with status, headers, body
    • Headers class with case-insensitive header handling

  3. Rewriter System: Apache mod_rewrite-like functionality

    • Conditional rules with regex patterns
    • Environment variable support
    • Rule chaining with [L], [R], [C] flags

  4. SAPI Implementation: Custom PHP SAPI in Rust

    • Direct Zend API usage for performance
    • Thread-safe with TSRM support
    • Reusable PHP environments across requests

Critical Development Notes

  1. System Dependencies Required:

    • Linux: libssl-dev libcurl4-openssl-dev libxml2-dev libsqlite3-dev libonig-dev re2c libpq5
    • macOS: openssl@3 curl sqlite libxml2 oniguruma postgresql@16

  2. PHP Runtime: Must have libphp.so (Linux) or libphp.dylib (macOS) in project root

  3. Testing: AVA framework with 3-minute timeout due to PHP startup overhead

  4. Type Definitions: index.d.ts is auto-generated by NAPI-RS - do not edit manually

  5. Platform Support: x64 Linux, x64/arm64 macOS (pre-built binaries in /npm)

  6. Recent Architecture Changes:

    • Consolidated from multi-crate workspace to single crate named php
    • NAPI support is now feature-gated with napi-support feature
    • Binary target supports both library (rlib) and dynamic library (cdylib) outputs

Common Tasks

Adding New NAPI Functions

  1. Implement in Rust under src/ with #[cfg(feature = "napi-support")]
  2. Use #[napi] attributes for exposed functions/classes
  3. Run npm run build to regenerate TypeScript definitions

Modifying Request/Response Handling

  • Core logic in src/sapi.rs and src/embed.rs
  • JavaScript wrapper in index.js
  • Request/response types from http-handler crate

Debugging PHP Issues

  • Check INTERNALS.md for PHP embedding details
  • Use npm run build:debug for debug symbols
  • PHP superglobals set via SG(...) macro in Rust code

Working with Rewriter Rules

The rewriter system supports Apache mod_rewrite-like functionality:

  • Create rules with conditions (header, host, method, path, query)
  • Apply rewriters (header, href, method, path, query, status)
  • Use flags like [L] (last), [R] (redirect), [C] (chain)
  • Example: new Rewriter([{ conditions: [{type: 'path', args: ['^/old/(.*)$']}], rewriters: [{type: 'path', args: ['^/old/(.*)$', '/new/$1']}] }])

Project Files Reference

  • index.js: Main JavaScript API, exports PHP, Request, Response, Headers, Rewriter classes
  • src/lib.rs: Library entry point, exports core types and NAPI bindings
  • src/main.rs: Binary entry point for standalone testing
  • src/embed.rs: Core Embed type for handling PHP requests
  • src/sapi.rs: PHP SAPI implementation (low-level PHP integration)
  • src/runtime.rs: NAPI runtime implementation (when napi-support feature enabled)
  • __test__/*.spec.mjs: Test files for each component