@php-wasm/universal 3.0.46 → 3.0.52

package/lib/index.d.ts

@@ -28,7 +28,7 @@ export type { MountHandler, UnmountFunction } from './php';
 export { loadPHPRuntime, popLoadedRuntime } from './load-php-runtime';
 export type { Emscripten } from './emscripten-types';
 export type { DataModule, EmscriptenOptions, PHPLoaderModule, PHPRuntime, PHPRuntimeId, RuntimeType, } from './load-php-runtime';
-export type { PHPRequestHandlerConfiguration, RewriteRule, } from './php-request-handler';
+export type { PHPRequestHandlerConfiguration, RewriteRule, PathAlias, } from './php-request-handler';
 export { PHPRequestHandler, applyRewriteRules, inferMimeType, } from './php-request-handler';
 export type { FileNotFoundGetActionCallback, FileNotFoundToInternalRedirect, FileNotFoundToResponse, FileNotFoundAction, CookieStore, } from './php-request-handler';
 export { rotatePHPRuntime } from './rotate-php-runtime';

package/lib/php-instance-manager.d.ts

@@ -28,11 +28,7 @@ export interface PHPInstanceManager extends AsyncDisposable {
     /**
      * Acquire a PHP instance for processing a request.
      *
-     * @param options.considerPrimary - Whether the primary instance can be used.
-     *        Set to false for operations that would corrupt the primary (e.g., CLI commands).
      * @returns An acquired PHP instance with a reap function.
      */
-    acquirePHPInstance(options?: {
-        considerPrimary?: boolean;
-    }): Promise<AcquiredPHP>;
+    acquirePHPInstance(): Promise<AcquiredPHP>;
 }

package/lib/php-process-manager.d.ts

@@ -6,24 +6,18 @@ export type PHPFactoryOptions = {
 export type PHPFactory = (options: PHPFactoryOptions) => Promise<PHP>;
 export interface ProcessManagerOptions {
     /**
-     * The maximum number of PHP instances that can exist at
+     * The maximum number of PHP instances that can be in use at
      * the same time.
      */
     maxPhpInstances?: number;
     /**
      * The number of milliseconds to wait for a PHP instance when
-     * we have reached the maximum number of PHP instances and
-     * cannot spawn a new one. If the timeout is reached, we assume
-     * all the PHP instances are deadlocked and a throw MaxPhpInstancesError.
+     * all instances are busy. If the timeout is reached, we assume
+     * all the PHP instances are deadlocked and throw MaxPhpInstancesError.
      *
-     * Default: 5000
+     * Default: 30000
      */
     timeout?: number;
-    /**
-     * The primary PHP instance that's never killed. This instance
-     * contains the reference filesystem used by all other PHP instances.
-     */
-    primaryPhp?: PHP;
     /**
      * A factory function used for spawning new PHP instances.
      */
@@ -33,86 +27,53 @@ export declare class MaxPhpInstancesError extends Error {
     constructor(limit: number);
 }
 /**
- * A PHP Process manager.
- *
- * Maintains:
- * * A single "primary" PHP instance that's never killed – it contains the
- *   reference filesystem used by all other PHP instances.
- * * A pool of disposable PHP instances that are spawned to handle a single
- *   request and reaped immediately after.
- *
- * When a new request comes in, PHPProcessManager yields the idle instance to
- * handle it, and immediately starts initializing a new idle instance. In other
- * words, for n concurrent requests, there are at most n+1 PHP instances
- * running at the same time.
+ * A PHP Process manager that maintains a pool of reusable PHP instances.
  *
- * A slight nuance is that the first idle instance is not initialized until the
- * first concurrent request comes in. This is because many use-cases won't
- * involve parallel requests and, for those, we can avoid eagerly spinning up a
- * second PHP instance.
+ * Instances are spawned on demand up to `maxPhpInstances` and reused across
+ * requests. The first instance spawned is the "primary" instance which
+ * contains the reference filesystem used by all other instances.
  *
- * This strategy is inspired by Cowboy, an Erlang HTTP server. Handling a
- * single extra request can happen immediately, while handling multiple extra
- * requests requires extra time to spin up a few PHP instances. This is a more
- * resource-friendly tradeoff than keeping 5 idle instances at all times.
+ * The semaphore controls how many requests can be processed concurrently.
+ * When all instances are busy, new requests wait in a queue until an
+ * instance becomes available or the timeout is reached.
  */
 export declare class PHPProcessManager implements PHPInstanceManager {
-    private primaryPhp?;
-    private primaryPhpPromise?;
-    private primaryIdle;
-    private nextInstance;
-    /**
-     * All spawned PHP instances, including the primary PHP instance.
-     * Used for bookkeeping and reaping all instances on dispose.
-     */
-    private allInstances;
-    private phpFactory?;
+    /** All PHP instances that have been spawned. */
+    private instances;
+    /** Instances that are currently idle and available for use. */
+    private idleInstances;
+    /** Maximum number of concurrent PHP instances allowed. */
     private maxPhpInstances;
+    /** Factory function for creating new PHP instances. */
+    private phpFactory?;
+    /** Controls concurrent access to PHP instances. */
     private semaphore;
+    /** Prevents spawning duplicate primary instances during concurrent calls. */
+    private primaryPhpPromise?;
     constructor(options?: ProcessManagerOptions);
     /**
-     * Get the primary PHP instance.
-     *
-     * If the primary PHP instance is not set, it will be spawned
-     * using the provided phpFactory.
-     *
-     * @throws {Error} when called twice before the first call is resolved.
+     * Get the primary PHP instance (the first one spawned).
+     * If no instance exists yet, one will be spawned and marked as idle.
      */
     getPrimaryPhp(): Promise<PHP>;
     /**
-     * Get a PHP instance.
-     *
-     * It could be either the primary PHP instance, an idle disposable PHP
-     * instance, or a newly spawned PHP instance – depending on the resource
-     * availability.
+     * Acquire a PHP instance for processing a request.
      *
-     * @param considerPrimary - Whether to consider the primary PHP instance.
-     *                          It matters because PHP.cli() sets the SAPI to CLI and
-     *                          kills the entire process after it finishes running,
-     *                          making the primary PHP instance non-reusable for
-     *                          subsequent .run() calls. This is fine for one-off
-     *                          child PHP instances, but not for the primary PHP
-     *                          that's meant to continue working for the entire duration
-     *                          of the ProcessManager lifetime. Therefore, we don't
-     *                          consider the primary PHP instance by default unless
-     *                          the caller explicitly requests it.
+     * Returns an idle instance from the pool, or spawns a new one if
+     * the pool isn't at capacity. If all instances are busy, waits
+     * until one becomes available.
      *
-     * @throws {MaxPhpInstancesError} when the maximum number of PHP instances is reached
-     *                                and the waiting timeout is exceeded.
+     * @throws {MaxPhpInstancesError} when the timeout is reached waiting
+     *                                for an available instance.
      */
-    acquirePHPInstance({ considerPrimary, }?: {
-        considerPrimary?: boolean;
-    }): Promise<AcquiredPHP>;
+    acquirePHPInstance(): Promise<AcquiredPHP>;
     /**
-     * Initiated spawning of a new PHP instance.
-     * This function is synchronous on purpose – it needs to synchronously
-     * add the spawn promise to the allInstances array without waiting
-     * for PHP to spawn.
+     * Get an idle instance or spawn a new one.
      */
-    private spawn;
+    private getOrSpawnInstance;
     /**
-     * Actually acquires the lock and spawns a new PHP instance.
+     * Spawn a new PHP instance.
      */
-    private doSpawn;
+    private spawnInstance;
     [Symbol.asyncDispose](): Promise<void>;
 }

package/lib/php-request-handler.d.ts

@@ -36,6 +36,26 @@ export interface CookieStore {
      */
     getCookieRequestHeader(): string;
 }
+/**
+ * Maps a URL path prefix to an absolute filesystem path.
+ * Similar to Nginx's `alias` directive or Apache's `Alias` directive.
+ *
+ * @example
+ * ```ts
+ * // Requests to /phpmyadmin/* will be served from /tools/phpmyadmin/*
+ * { urlPrefix: '/phpmyadmin', fsPath: '/tools/phpmyadmin' }
+ * ```
+ */
+export type PathAlias = {
+    /**
+     * The URL path prefix to match (e.g., '/phpmyadmin').
+     */
+    urlPrefix: string;
+    /**
+     * The absolute filesystem path to serve files from.
+     */
+    fsPath: string;
+};
 interface BaseConfiguration {
     /**
      * The directory in the PHP filesystem where the server will look
@@ -50,6 +70,18 @@ interface BaseConfiguration {
      * Rewrite rules
      */
     rewriteRules?: RewriteRule[];
+    /**
+     * Path aliases that map URL prefixes to filesystem paths outside
+     * the document root. Similar to Nginx's `alias` directive.
+     *
+     * @example
+     * ```ts
+     * pathAliases: [
+     *   { urlPrefix: '/phpmyadmin', fsPath: '/tools/phpmyadmin' }
+     * ]
+     * ```
+     */
+    pathAliases?: PathAlias[];
     /**
      * A callback that decides how to handle a file-not-found condition for a
      * given request URI.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@php-wasm/universal",
-  "version": "3.0.46",
+  "version": "3.0.52",
   "description": "PHP.wasm – emscripten bindings for PHP",
   "repository": {
     "type": "git",
@@ -37,18 +37,18 @@
   "module": "./index.js",
   "types": "index.d.ts",
   "license": "GPL-2.0-or-later",
-  "gitHead": "845cbc01dba047db8bf0b4ae2670b924e3517087",
+  "gitHead": "fd79b4d41ec8858ecacde7a814818fac95c40246",
   "engines": {
     "node": ">=20.18.3",
     "npm": ">=10.1.0"
   },
   "dependencies": {
     "ini": "4.1.2",
-    "@php-wasm/node-polyfills": "3.0.46",
-    "@php-wasm/logger": "3.0.46",
-    "@php-wasm/util": "3.0.46",
-    "@php-wasm/stream-compression": "3.0.46",
-    "@php-wasm/progress": "3.0.46"
+    "@php-wasm/node-polyfills": "3.0.52",
+    "@php-wasm/logger": "3.0.52",
+    "@php-wasm/util": "3.0.52",
+    "@php-wasm/stream-compression": "3.0.52",
+    "@php-wasm/progress": "3.0.52"
   },
   "packageManager": "npm@10.9.2",
   "overrides": {
@@ -59,7 +59,9 @@
     "@playwright/test": "1.55.1",
     "ws": "8.18.3",
     "tmp": "0.2.5",
-    "form-data": "^4.0.4"
+    "form-data": "^4.0.4",
+    "lodash": "^4.17.23",
+    "glob": "^9.3.0"
   },
   "optionalDependencies": {
     "fs-ext": "2.1.1"