Initial commit for jsphp engine, PHP 8.5 parser, runtime, extensions, CLI, and WordPress tests

Author: ktaeyln

.gitignore

@@ -0,0 +1,8 @@
+node_modules/
+tests/cache/
+*.zip
+wordpress/
+coverage/
+.cache/
+tests/latest.zip
+.idea/

AGENTS.md

@@ -0,0 +1,20 @@
+# AI Agent Guidelines for `node-jsphp`
+
+This document provides operational context and guidance for AI agents working on the `node-jsphp` codebase.
+
+## Core Directives
+
+1. **Synchronous PHP / Asynchronous JS**:
+   PHP code semantics appear synchronous to the PHP script, but generated JavaScript code MUST run asynchronously using `async/await` so Node.js can handle concurrent requests without blocking.
+
+2. **Stack Trace Masking**:
+   Never expose raw JavaScript execution stack frames to PHP. Standardize all stack traces in `PHPError` to reflect PHP line numbers or `[INTERNAL]`.
+
+3. **No Build Output Directory for Sources**:
+   TypeScript source files in `src/` must compile to JavaScript `.js` and declaration `.d.ts` files placed directly alongside their corresponding `.ts` sources. Do NOT use a `dist/` or `out/` folder.
+
+4. **AST Optimization Rules**:
+   Always ensure optimizer handles `extension_loaded(...)`, `defined(...)`, and boolean expressions at compile time. Eliminate unreachable `if` branches before generating JS output.
+
+5. **WordPress & MySQL Compatibility**:
+   Maintain full compatibility with WordPress database operations and standard themes.

README.md

@@ -0,0 +1,110 @@
+# jsphp (`node-jsphp`)
+
+`jsphp` is a high-performance Node.js runtime, CLI, and transpiler engine for **PHP 8.5** written in TypeScript. It parses PHP code into ASTs, optimizes execution through constant folding and dead-code elimination, and transpiles PHP to asynchronous JavaScript source code with source maps (`.js.map`).
+
+`jsphp` enables running PHP scripts, applications (including full **WordPress** sites), and command-line interfaces directly inside Node.js without needing native PHP binaries or socket connections to PHP-FPM.
+
+---
+
+## Features
+
+- **PHP 8.5 Support**: Full support for PHP 8.5 language constructs, functions, and standard library.
+- **Asynchronous Execution Model**: All transpiled JavaScript code runs asynchronously via `async/await`, preventing blocking of Node.js event loop while executing PHP synchronously from PHP's perspective.
+- **Transparent Stack Trace Virtualization**: JavaScript stack traces are filtered and mapped to PHP file and line locations, displaying internal Node.js frames as `[INTERNAL]`.
+- **AST Optimization**: Precalculates constants, eliminates unreachable branches (`if(false)`, `if(extension_loaded(...))`, `defined(...)`), and folds expressions at compile time.
+- **On-Disk Transpilation Cache**: Saves compiled JavaScript files and sourcemaps to `process.env.JSPHP_CACHE` under `${JSPHP_CACHE}/${EngineConfigSHA1}/${FilePathSHA1}.js`.
+- **Live File Watching**: Uses `chokidar` to automatically invalidate and recompile cached files when PHP source files are updated.
+- **Built-in PHP Extensions**: Full implementations of `mysqli` (via `mysql2`), `pdo`, `pdo_mysql`, `gd` (via `sharp`), `pcre`, `mbstring`, `json`, `curl`, `session`, `xml`, `spl`, `hash`, `openssl`, and more.
+- **CLI & REPL**: `php` CLI tool supporting `-v`, `-r <code>`, `-a` interactive shell, and script execution.
+
+---
+
+## Installation
+
+```bash
+npm install jsphp
+```
+
+---
+
+## Usage
+
+### 1. Basic PHP Code Execution
+
+```typescript
+import { PHPEngine } from "jsphp";
+
+async function main() {
+  const engine = new PHPEngine();
+  const ctx = engine.createContext({
+    stdout: (data) => process.stdout.write(data),
+  });
+
+  await ctx.eval(`
+    <?php
+    $name = "JSPHP";
+    echo "Hello, " . $name . "!\n";
+  `);
+
+  engine.close();
+}
+
+main();
+```
+
+### 2. Running a PHP File
+
+```typescript
+import { PHPContext } from "jsphp";
+
+async function run() {
+  await PHPContext.runFile("./index.php", {
+    stdout: (data) => process.stdout.write(data),
+  });
+}
+
+run();
+```
+
+### 3. Command Line Interface (CLI)
+
+```bash
+# Print PHP version
+npx php -v
+
+# Evaluate inline code
+npx php -r "echo 'Hello from CLI!';"
+
+# Interactive REPL shell
+npx php -a
+
+# Run script file
+npx php index.php
+```
+
+---
+
+## Architecture & Documentation
+
+Detailed documentation can be found in the `docs/` directory:
+- [docs/architecture.md](docs/architecture.md): Overview of `PHPEngine`, `PHPContext`, and execution model.
+- [docs/transpiler.md](docs/transpiler.md): Details on AST parser, optimizer, sourcemaps, and cache hashing.
+- [docs/extensions.md](docs/extensions.md): Creating custom `PHPExtension` classes and registering functions/classes.
+
+---
+
+## Running Tests
+
+```bash
+# Run unit tests
+npm test
+
+# Run WordPress integration tests (requires local MySQL instance)
+MYSQL_ROOT_PASSWORD="DNESB*GJ*W(E$GYB$UW#gt78wg" npm test
+```
+
+---
+
+## License
+
+[MIT](LICENSE.md)

bin/php-fpm.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+const { runFPM } = require("../src/cli/php-fpm");
+
+runFPM().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

bin/php.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+const { runCLI } = require("../src/cli/php");
+
+runCLI(process.argv.slice(2)).catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

docs/architecture.md

@@ -0,0 +1,17 @@
+# Architecture Overview
+
+`jsphp` consists of three core layers:
+
+1. **`PHPEngine`**:
+   - Manages loaded extensions, core functions, constants, and classes.
+   - Computes configuration SHA1 hash based on active extensions and defines.
+   - Manages file watching via `chokidar` and compilation caching.
+
+2. **`PHPContext`**:
+   - Manages per-request runtime state, environment variables, working directory, output buffers, and superglobals (`$_GET`, `$_POST`, `$_SERVER`, etc.).
+   - Executes compiled JS functions within its isolated scope.
+
+3. **AST Parser, Optimizer & Transpiler**:
+   - Parses PHP 8.5 code into an AST representation.
+   - Optimizes constant expressions and dead code branches.
+   - Transpiles AST nodes into JS functions taking a `PHPContext` argument.

docs/extensions.md

@@ -0,0 +1,31 @@
+# Extension System
+
+Extensions in `jsphp` extend the abstract class `PHPExtension`:
+
+```typescript
+import { PHPExtension, PHPEngine, PHPContext } from "jsphp";
+
+export class CustomExtension extends PHPExtension {
+  public readonly name = "custom";
+
+  public onInit(engine: PHPEngine): void {
+    this.constants = {
+      CUSTOM_CONST: 42,
+    };
+
+    this.functions = {
+      custom_hello: (ctx: PHPContext, name: string) => {
+        return `Hello, ${name}!`;
+      },
+    };
+  }
+}
+```
+
+Registering a custom extension:
+
+```typescript
+const engine = new PHPEngine({
+  extensions: [new CustomExtension()],
+});
+```

docs/transpiler.md

@@ -0,0 +1,14 @@
+# AST Optimizer & Transpiler
+
+## Optimization Pipeline
+
+1. **`PHPParser`**: Parses PHP source code into AST.
+2. **`ASTOptimizer`**:
+   - Replaces `extension_loaded("ext")` calls with `true` or `false` based on engine configuration.
+   - Replaces `defined("CONST")` with `true` or `false`.
+   - Prunes `if (false)` branches.
+   - Unwraps `if (true)` blocks.
+3. **`JSTranspiler`**:
+   - Generates async JavaScript code using `ctx.getVar()`, `ctx.setVar()`, `ctx.echo()`, and `await ctx.callFunction()`.
+   - Generates source maps (`.js.map`).
+   - Writes compiled outputs to disk cache at `${process.env.JSPHP_CACHE}/${EngineSHA1}/${FilePathSHA1}.js`.

index.d.ts

@@ -0,0 +1,10 @@
+export { PHPEngine, PHPEngineOptions } from "./src/PHPEngine";
+export { PHPContext, PHPContextOptions } from "./src/PHPContext";
+export { PHPExtension } from "./src/PHPExtension";
+export { PHPError, PHPException, PHPTypeError, PHPParseError, PHPFatalError } from "./src/runtime/errors/PHPError";
+export { PHPObject, PHPClass } from "./src/runtime/objects/PHPObject";
+export { Superglobals } from "./src/runtime/superglobals/Superglobals";
+export { OutputBufferStack } from "./src/runtime/output/OutputBuffer";
+export { PHPParser } from "./src/parser/PHPParser";
+export { ASTOptimizer } from "./src/parser/ASTOptimizer";
+export { JSTranspiler } from "./src/parser/JSTranspiler";