feat: add nodejs extension interop, http server URL resolution, internalVars, PHPResponse header/cookie lifecycle, and set_error_handler support

Author: ktaeyln

.gitignore

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

AGENTS.md

@@ -1,20 +1,40 @@
-# AI Agent Guidelines for `node-jsphp`
+# AI Agent Guidelines for `node-jsphp` (`@nexustools/php`)
 
-This document provides operational context and guidance for AI agents working on the `node-jsphp` codebase.
+This document provides operational context, architecture directives, and guidance for AI agents working on the `@nexustools/php` 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.
+   PHP code semantics appear synchronous to the PHP script, but transpiled JavaScript code MUST run asynchronously using `async/await` so Node.js can handle concurrent execution without blocking the event loop.
 
-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]`.
+2. **Stack Trace Virtualization**:
+   Never expose raw JavaScript execution stack frames to PHP. Standardize all stack traces in `PHPError` to reflect PHP source 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.
+   TypeScript source files in `src/` 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.
+   Ensure `ASTOptimizer` optimizes `extension_loaded(...)`, `defined(...)`, `constant(...)`, constant references (`name` / `constref`), and boolean expressions at compile time. Eliminate dead `if` branches prior to code generation.
 
-5. **WordPress & MySQL Compatibility**:
-   Maintain full compatibility with WordPress database operations and standard themes.
+5. **CLI & Server Binaries**:
+   - `php` (`bin/php.js`): Single-file CLI execution binary.
+   - `php-fpm` (`bin/php-fpm.js`): FastCGI (FCGI 1.0) binary socket server for Nginx/Apache proxying.
+   - `php-http-server` (`bin/php-http-server.js`): HTTP web server supporting static file serving and smart URL resolution (`/` -> `index.php`/`index.html`, `/test` -> `test.php`/`test.html`/`test/index.php`).
+
+6. **Internal Variables (`internalVars`)**:
+   `PHPEngine` and `PHPContext` maintain `internalVars` (`Map<string, any>`) that are invisible to PHP userland (`$GLOBALS`, `get_defined_vars()`, Reflection), but accessible to internal engine methods, AST optimization, and server handlers.
+
+7. **Header & Response Lifecycle**:
+   HTTP response functions (`header`, `setcookie`, `setrawcookie`, `header_remove`, `headers_list`, `headers_sent`, `http_response_code`) operate on `PHPResponse` attached to `PHPContext`. Calling header functions in CLI mode without a registered server response handler throws a `PHPWarning` / `PHPError`.
+
+8. **Error Handling & `set_error_handler`**:
+   Supports `set_error_handler`, `restore_error_handler`, `trigger_error`, `error_reporting`, and `ErrorException`. Errors thrown within PHP methods use subclasses of `PHPError` (`PHPFatalError`, `PHPWarning`, `PHPNotice`, `PHPTypeError`, etc.).
+
+9. **Reflection Metadata & JS Source Fallback**:
+   Function/method metadata is tracked via `.phpMeta` attached by `defineFunction`. If `.phpMeta` is absent, `ReflectionFunction` and `ReflectionMethod` fall back to parsing the function's JavaScript `.toString()` source declaration.
+
+10. **Optional Node.js Interop (`nodejs` extension)**:
+    Provides Node.js module/package loading (`nodejs_require`), global variable access (`nodejs_global`), eval (`nodejs_eval`), and instantiation (`nodejs_new` / `NodeJS` class) wrapped via `NodeJSObject`.
+
+11. **WordPress & MySQL Compatibility**:
+    Maintain full compatibility with WordPress database operations (`mysqli`), installation flows, and theme/admin dashboard rendering tested against a local MySQL database.

index.d.ts

@@ -1,11 +1,14 @@
 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 { PHPError, PHPException, PHPTypeError, PHPParseError, PHPFatalError, PHPNotice, PHPWarning, ErrorException, } from "./src/runtime/errors/PHPError";
 export { PHPObject, PHPClass, PHPMethodMetadata, PHPPropertyMetadata, PHPParameterMetadata } 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";
+export { runHTTPServer } from "./src/cli/php-http-server";
+export { runFPM } from "./src/cli/php-fpm";
 export { defineFunction, FunctionMetaOptions, Reflection, ReflectionClass, ReflectionMethod, ReflectionProperty, ReflectionFunction, ReflectionParameter, ReflectionType, } from "./src/runtime/reflection/Reflection";
+export { NodeJSExtension, NodeJSObject, NodeJSService, wrapJSValue, unwrapPHPValue, } from "./src/extensions/nodejs/nodejs";

index.js

@@ -1,13 +1,24 @@
 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 {
+  PHPError,
+  PHPException,
+  PHPTypeError,
+  PHPParseError,
+  PHPFatalError,
+  PHPNotice,
+  PHPWarning,
+  ErrorException,
+} from "./src/runtime/errors/PHPError";
 export { PHPObject, PHPClass, PHPMethodMetadata, PHPPropertyMetadata, PHPParameterMetadata } 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";
+export { runHTTPServer } from "./src/cli/php-http-server";
+export { runFPM } from "./src/cli/php-fpm";
 export {
   defineFunction,
   FunctionMetaOptions,
@@ -19,3 +30,10 @@ export {
   ReflectionParameter,
   ReflectionType,
 } from "./src/runtime/reflection/Reflection";
+export {
+  NodeJSExtension,
+  NodeJSObject,
+  NodeJSService,
+  wrapJSValue,
+  unwrapPHPValue,
+} from "./src/extensions/nodejs/nodejs";

index.js.map

@@ -8,19 +8,45 @@ export interface PHPContextOptions {
     stdout?: Writable | ((data: string) => void);
     stderr?: Writable | ((data: string) => void);
     superglobals?: SuperglobalsOptions;
+    errorReporting?: number;
+}
+export declare class PHPResponse {
+    statusCode: number;
+    headers: {
+        name: string;
+        value: string;
+    }[];
+    headersSent: boolean;
+    setHeader(name: string, value: string, replace?: boolean): void;
+    removeHeader(name?: string): void;
+    getHeader(name: string): string | undefined;
+    getHeadersList(): string[];
+    setCookie(name: string, value?: string, expires?: number, path?: string, domain?: string, secure?: boolean, httponly?: boolean, raw?: boolean): void;
 }
 export declare class PHPContext {
     engine: PHPEngine;
     cwd: string;
     env: Record<string, string>;
     vars: Record<string, any>;
+    internalVars: Map<string, any>;
     superglobals: Superglobals;
     outputBuffer: OutputBufferStack;
+    response: PHPResponse;
+    errorHandlerStack: any[];
+    errorReportingLevel: number;
     includedFiles: Set<string>;
     private stdout;
     private stderr;
     outputText: string;
     constructor(engine: PHPEngine, options?: PHPContextOptions);
+    setErrorHandler(handler: any, levels?: number): any;
+    restoreErrorHandler(): boolean;
+    triggerError(message: string, level?: number, file?: string, line?: number): Promise<boolean>;
+    getInternalVar(name: string): any;
+    setInternalVar(name: string, value: any): void;
+    get responseHeaders(): Record<string, string>;
+    get statusCode(): number;
+    flushHeaders(): void;
     echo(data: any): Promise<void>;
     private writeStdout;
     getConstant(name: string): any;