@php-wasm/universal 0.5.6 → 0.6.0

package/lib/base-php.d.ts

@@ -3,6 +3,7 @@ import { PHPRequestHandlerConfiguration } from './php-request-handler';
 import { PHPResponse } from './php-response';
 import type { PHPRuntimeId } from './load-php-runtime';
 import { IsomorphicLocalPHP, MessageListener, PHPRequest, PHPRequestHeaders, PHPRunOptions, RmDirOptions, ListFilesOptions, SpawnHandler, PHPEventListener, PHPEvent } from './universal-php';
+import { Semaphore } from '../../../util/src/index.ts';
 export declare const __private__dont__use: unique symbol;
 /**
  * An environment-agnostic wrapper around the Emscripten PHP runtime
@@ -16,6 +17,11 @@ export declare abstract class BasePHP implements IsomorphicLocalPHP {
     #private;
     protected [__private__dont__use]: any;
     requestHandler?: PHPBrowser;
+    /**
+     * An exclusive lock that prevent multiple requests from running at
+     * the same time.
+     */
+    semaphore: Semaphore;
     /**
      * Initializes a PHP runtime.
      *
@@ -30,7 +36,7 @@ export declare abstract class BasePHP implements IsomorphicLocalPHP {
     /** @inheritDoc */
     onMessage(listener: MessageListener): Promise<void>;
     /** @inheritDoc */
-    setSpawnHandler(handler: SpawnHandler): Promise<void>;
+    setSpawnHandler(handler: SpawnHandler | string): Promise<void>;
     /** @inheritDoc */
     get absoluteUrl(): string;
     /** @inheritDoc */
@@ -41,6 +47,8 @@ export declare abstract class BasePHP implements IsomorphicLocalPHP {
     internalUrlToPath(internalUrl: string): string;
     initializeRuntime(runtimeId: PHPRuntimeId): void;
     /** @inheritDoc */
+    setSapiName(newName: string): Promise<void>;
+    /** @inheritDoc */
     setPhpIniPath(path: string): void;
     /** @inheritDoc */
     setPhpIniEntry(key: string, value: string): void;
@@ -51,7 +59,7 @@ export declare abstract class BasePHP implements IsomorphicLocalPHP {
     /** @inheritDoc */
     run(request: PHPRunOptions): Promise<PHPResponse>;
     addServerGlobalEntry(key: string, value: string): void;
-    defineConstant(key: string, value: string | number | null): void;
+    defineConstant(key: string, value: string | boolean | number | null): void;
     /** @inheritDoc */
     mkdir(path: string): void;
     /** @inheritDoc */
@@ -74,6 +82,13 @@ export declare abstract class BasePHP implements IsomorphicLocalPHP {
     isDir(path: string): boolean;
     /** @inheritDoc */
     fileExists(path: string): boolean;
-    exit(code?: number): any;
+    /**
+     * Hot-swaps the PHP runtime for a new one without
+     * interrupting the operations of this PHP instance.
+     *
+     * @param runtime
+     */
+    hotSwapPHPRuntime(runtime: number): void;
+    exit(code?: number): void;
 }
 export declare function normalizeHeaders(headers: PHPRequestHeaders): PHPRequestHeaders;

package/lib/index.d.ts

@@ -20,5 +20,6 @@ export type { PHPRequestHandlerConfiguration } from './php-request-handler';
 export { PHPRequestHandler } from './php-request-handler';
 export type { PHPBrowserConfiguration } from './php-browser';
 export { PHPBrowser } from './php-browser';
+export { rotatePHPRuntime } from './rotate-php-runtime';
 export { DEFAULT_BASE_URL, ensurePathPrefix, removePathPrefix, toRelativeUrl, } from './urls';
 export { isExitCodeZero } from './is-exit-code-zero';

package/lib/load-php-runtime.d.ts

@@ -112,10 +112,9 @@
  * @public
  * @param  phpLoaderModule         - The ESM-wrapped Emscripten module. Consult the Dockerfile for the build process.
  * @param  phpModuleArgs           - The Emscripten module arguments, see https://emscripten.org/docs/api_reference/module.html#affecting-execution.
- * @param  dataDependenciesModules - A list of the ESM-wrapped Emscripten data dependency modules.
  * @returns Loaded runtime id.
  */
-export declare function loadPHPRuntime(phpLoaderModule: PHPLoaderModule, phpModuleArgs?: EmscriptenOptions, dataDependenciesModules?: DataModule[]): Promise<number>;
+export declare function loadPHPRuntime(phpLoaderModule: PHPLoaderModule, phpModuleArgs?: EmscriptenOptions): Promise<number>;
 export type RuntimeType = 'NODE' | 'WEB' | 'WORKER';
 export type PHPRuntimeId = number;
 export declare function getLoadedRuntime(id: PHPRuntimeId): PHPRuntime;
@@ -140,7 +139,6 @@ export type EmscriptenOptions = {
     ENV?: Record<string, string>;
     locateFile?: (path: string) => string;
     noInitialRun?: boolean;
-    dataFileDownloads?: Record<string, number>;
     print?: (message: string) => void;
     printErr?: (message: string) => void;
     quit?: (status: number, toThrow: any) => void;

package/lib/rotate-php-runtime.d.ts

@@ -0,0 +1,23 @@
+import { BasePHP } from './base-php';
+export interface RotateOptions<T extends BasePHP> {
+    php: T;
+    recreateRuntime: () => Promise<number> | number;
+    maxRequests: number;
+}
+/**
+ * Listens to PHP events and swaps the internal PHP Runtime for a fresh one
+ * after a certain number of run() calls (which are responsible for handling
+ * HTTP requests).
+ *
+ * Why? Because PHP and PHP extension have a memory leak. Each request leaves
+ * the memory a bit more fragmented and with a bit less available space than
+ * before. Eventually, new allocations start failing.
+ *
+ * Rotating the PHP instance may seem like a workaround, but it's actually
+ * what PHP-FPM does natively:
+ *
+ * https://www.php.net/manual/en/install.fpm.configuration.php#pm.max-tasks
+ *
+ * @return cleanup function to restore
+ */
+export declare function rotatePHPRuntime<T extends BasePHP>({ php, recreateRuntime, maxRequests, }: RotateOptions<T>): () => void;

package/lib/universal-php.d.ts

@@ -1,17 +1,29 @@
 import { Remote } from 'comlink';
 import { PHPResponse } from './php-response';
 /**
- * Represents an event related to the PHP filesystem.
+ * Represents an event related to the PHP request.
  */
 export interface PHPRequestEndEvent {
     type: 'request.end';
 }
+/**
+ * Represents a PHP runtime initialization event.
+ */
+export interface PHPRuntimeInitializedEvent {
+    type: 'runtime.initialized';
+}
+/**
+ * Represents a PHP runtime destruction event.
+ */
+export interface PHPRuntimeBeforeDestroyEvent {
+    type: 'runtime.beforedestroy';
+}
 /**
  * Represents an event related to the PHP instance.
  * This is intentionally not an extension of CustomEvent
  * to make it isomorphic between different JavaScript runtimes.
  */
-export type PHPEvent = PHPRequestEndEvent;
+export type PHPEvent = PHPRequestEndEvent | PHPRuntimeInitializedEvent | PHPRuntimeBeforeDestroyEvent;
 /**
  * A callback function that handles PHP events.
  */
@@ -147,6 +159,11 @@ export interface RequestHandler {
     documentRoot: string;
 }
 export interface IsomorphicLocalPHP extends RequestHandler {
+    /**
+     * Sets the SAPI name exposed by the PHP module.
+     * @param newName - The new SAPI name.
+     */
+    setSapiName(newName: string): void;
     /**
      * Defines a constant in the PHP runtime.
      * @param key - The name of the constant.
@@ -384,7 +401,7 @@ export interface IsomorphicLocalPHP extends RequestHandler {
      *
      * @param handler Callback function to spawn a process.
      */
-    setSpawnHandler(handler: SpawnHandler): void;
+    setSpawnHandler(handler: SpawnHandler | string): void;
 }
 export type MessageListener = (data: string) => Promise<string | Uint8Array | void> | string | void;
 interface EventEmitter {
@@ -395,7 +412,7 @@ type ChildProcess = EventEmitter & {
     stdout: EventEmitter;
     stderr: EventEmitter;
 };
-export type SpawnHandler = (command: string) => ChildProcess;
+export type SpawnHandler = (command: string, args: string[]) => ChildProcess;
 export type IsomorphicRemotePHP = Remote<IsomorphicLocalPHP>;
 export type UniversalPHP = IsomorphicLocalPHP | IsomorphicRemotePHP;
 export type HTTPMethod = 'GET' | 'POST' | 'HEAD' | 'OPTIONS' | 'PATCH' | 'PUT' | 'DELETE';
@@ -460,6 +477,11 @@ export interface PHPRunOptions {
      * The code snippet to eval instead of a php file.
      */
     code?: string;
+    /**
+     * Whether to throw an error if the PHP process exits with a non-zero code
+     * or outputs to stderr.
+     */
+    throwOnError?: boolean;
 }
 /**
  * Output of the PHP.wasm runtime.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@php-wasm/universal",
-	"version": "0.5.6",
+	"version": "0.6.0",
 	"description": "PHP.wasm – emscripten bindings for PHP",
 	"repository": {
 		"type": "git",
@@ -36,7 +36,7 @@
 	"main": "./index.cjs",
 	"module": "./index.js",
 	"license": "GPL-2.0-or-later",
-	"gitHead": "72e190ebb407051ccb5ef544e2a62018395395a0",
+	"gitHead": "3f137306ec8e3b10ec0674a1fe69ee43349edb4a",
 	"engines": {
 		"node": ">=18.18.2",
 		"npm": ">=8.11.0"