@wp-playground/blueprints 0.6.15 → 0.7.0

package/index.d.ts

@@ -217,137 +217,17 @@ export type PHPEvent = PHPRequestEndEvent | PHPRequestErrorEvent | PHPRuntimeIni
  * A callback function that handles PHP events.
  */
 export type PHPEventListener = (event: PHPEvent) => void;
-/**
- * Handles HTTP requests using PHP runtime as a backend.
- *
- * @public
- * @example Use PHPRequestHandler implicitly with a new PHP instance:
- * ```js
- * import { PHP } from '@php-wasm/web';
- *
- * const php = await PHP.load( '7.4', {
- *     requestHandler: {
- *         // PHP FS path to serve the files from:
- *         documentRoot: '/www',
- *
- *         // Used to populate $_SERVER['SERVER_NAME'] etc.:
- *         absoluteUrl: 'http://127.0.0.1'
- *     }
- * } );
- *
- * php.mkdirTree('/www');
- * php.writeFile('/www/index.php', '<?php echo "Hi from PHP!"; ');
- *
- * const response = await php.request({ path: '/index.php' });
- * console.log(response.text);
- * // "Hi from PHP!"
- * ```
- *
- * @example Explicitly create a PHPRequestHandler instance and run a PHP script:
- * ```js
- * import {
- *   loadPHPRuntime,
- *   PHP,
- *   PHPRequestHandler,
- *   getPHPLoaderModule,
- * } from '@php-wasm/web';
- *
- * const runtime = await loadPHPRuntime( await getPHPLoaderModule('7.4') );
- * const php = new PHP( runtime );
- *
- * php.mkdirTree('/www');
- * php.writeFile('/www/index.php', '<?php echo "Hi from PHP!"; ');
- *
- * const server = new PHPRequestHandler(php, {
- *     // PHP FS path to serve the files from:
- *     documentRoot: '/www',
- *
- *     // Used to populate $_SERVER['SERVER_NAME'] etc.:
- *     absoluteUrl: 'http://127.0.0.1'
- * });
- *
- * const response = server.request({ path: '/index.php' });
- * console.log(response.text);
- * // "Hi from PHP!"
- * ```
- */
-export interface RequestHandler {
-	/**
-	 * Serves the request – either by serving a static file, or by
-	 * dispatching it to the PHP runtime.
-	 *
-	 * The request() method mode behaves like a web server and only works if
-	 * the PHP was initialized with a `requestHandler` option (which the online version
-	 * of WordPress Playground does by default).
-	 *
-	 * In the request mode, you pass an object containing the request information
-	 * (method, headers, body, etc.) and the path to the PHP file to run:
-	 *
-	 * ```ts
-	 * const php = PHP.load('7.4', {
-	 * 	requestHandler: {
-	 * 		documentRoot: "/www"
-	 * 	}
-	 * })
-	 * php.writeFile("/www/index.php", `<?php echo file_get_contents("php://input");`);
-	 * const result = await php.request({
-	 * 	method: "GET",
-	 * 	headers: {
-	 * 		"Content-Type": "text/plain"
-	 * 	},
-	 * 	body: "Hello world!",
-	 * 	path: "/www/index.php"
-	 * });
-	 * // result.text === "Hello world!"
-	 * ```
-	 *
-	 * The `request()` method cannot be used in conjunction with `cli()`.
-	 *
-	 * @example
-	 * ```js
-	 * const output = await php.request({
-	 * 	method: 'GET',
-	 * 	url: '/index.php',
-	 * 	headers: {
-	 * 		'X-foo': 'bar',
-	 * 	},
-	 * 	body: {
-	 * 		foo: 'bar',
-	 * 	},
-	 * });
-	 * console.log(output.stdout); // "Hello world!"
-	 * ```
-	 *
-	 * @param  request - PHP Request data.
-	 */
-	request(request: PHPRequest, maxRedirects?: number): Promise<PHPResponse>;
-	/**
-	 * Converts a path to an absolute URL based at the PHPRequestHandler
-	 * root.
-	 *
-	 * @param  path The server path to convert to an absolute URL.
-	 * @returns The absolute URL.
-	 */
+export interface IsomorphicLocalPHP {
+	/** @deprecated Use PHPRequestHandler instead. */
+	request(request: PHPRequest): Promise<PHPResponse>;
+	/** @deprecated Use PHPRequestHandler instead. */
 	pathToInternalUrl(path: string): string;
-	/**
-	 * Converts an absolute URL based at the PHPRequestHandler to a relative path
-	 * without the server pathname and scope.
-	 *
-	 * @param  internalUrl An absolute URL based at the PHPRequestHandler root.
-	 * @returns The relative path.
-	 */
+	/** @deprecated Use PHPRequestHandler instead. */
 	internalUrlToPath(internalUrl: string): string;
-	/**
-	 * The absolute URL of this PHPRequestHandler instance.
-	 */
+	/** @deprecated Use PHPRequestHandler instead. */
 	absoluteUrl: string;
-	/**
-	 * The directory in the PHP filesystem where the server will look
-	 * for the files to serve. Default: `/var/www`.
-	 */
+	/** @deprecated Use PHPRequestHandler instead. */
 	documentRoot: string;
-}
-export interface IsomorphicLocalPHP extends RequestHandler {
 	/**
 	 * Sets the SAPI name exposed by the PHP module.
 	 * @param newName - The new SAPI name.
@@ -583,25 +463,8 @@ export interface IsomorphicLocalPHP extends RequestHandler {
 	 * @param listener Callback function to handle the message.
 	 */
 	onMessage(listener: MessageListener): void;
-	/**
-	 * Registers a handler to spawns a child process when
-	 * `proc_open()`, `popen()`, `exec()`, `system()`, or `passthru()`
-	 * is called.
-	 *
-	 * @param handler Callback function to spawn a process.
-	 */
-	setSpawnHandler(handler: SpawnHandler | string): void;
 }
 export type MessageListener = (data: string) => Promise<string | Uint8Array | void> | string | void;
-export interface EventEmitter {
-	on(event: string, listener: (...args: any[]) => void): this;
-	emit(event: string, ...args: any[]): boolean;
-}
-export type ChildProcess = EventEmitter & {
-	stdout: EventEmitter;
-	stderr: EventEmitter;
-};
-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";
@@ -655,6 +518,10 @@ export interface PHPRunOptions {
 	 * Environment variables to set for this run.
 	 */
 	env?: Record<string, string>;
+	/**
+	 * $_SERVER entries to set for this run.
+	 */
+	$_SERVER?: Record<string, string>;
 	/**
 	 * The code snippet to eval instead of a php file.
 	 */
@@ -689,13 +556,22 @@ export type SupportedPHPVersion = (typeof SupportedPHPVersions)[number];
 export type SupportedPHPExtension = "iconv" | "mbstring" | "xml-bundle" | "gd";
 export type SupportedPHPExtensionBundle = "kitchen-sink" | "light";
 export interface SemaphoreOptions {
+	/**
+	 * The maximum number of concurrent locks.
+	 */
 	concurrency: number;
+	/**
+	 * The maximum time to wait for a lock to become available.
+	 */
+	timeout?: number;
 }
 declare class Semaphore {
 	private _running;
 	private concurrency;
+	private timeout?;
 	private queue;
-	constructor({ concurrency }: SemaphoreOptions);
+	constructor({ concurrency, timeout }: SemaphoreOptions);
+	get remaining(): number;
 	get running(): number;
 	acquire(): Promise<() => void>;
 	run<T>(fn: () => T | Promise<T>): Promise<T>;
@@ -1324,30 +1200,6 @@ export interface MvStep {
  * Moves a file or directory from one path to another.
  */
 export declare const mv: StepHandler<MvStep>;
-/**
- * @inheritDoc setPhpIniEntry
- * @hasRunnableExample
- * @example
- *
- * <code>
- * {
- * 		"step": "setPhpIniEntry",
- * 		"key": "display_errors",
- * 		"value": "1"
- * }
- * </code>
- */
-export interface SetPhpIniEntryStep {
-	step: "setPhpIniEntry";
-	/** Entry name e.g. "display_errors" */
-	key: string;
-	/** Entry value as a string e.g. "1" */
-	value: string;
-}
-/**
- * Sets a PHP ini entry.
- */
-export declare const setPhpIniEntry: StepHandler<SetPhpIniEntryStep>;
 /**
  * @inheritDoc runPHP
  * @hasRunnableExample
@@ -1692,7 +1544,7 @@ export type StepDefinition = Step & {
  * If you add a step here, make sure to also
  * add it to the exports below.
  */
-export type GenericStep<Resource> = ActivatePluginStep | ActivateThemeStep | CpStep | DefineWpConfigConstsStep | DefineSiteUrlStep | EnableMultisiteStep | ImportWxrStep<Resource> | ImportWordPressFilesStep<Resource> | InstallPluginStep<Resource> | InstallThemeStep<Resource> | LoginStep | MkdirStep | MvStep | RequestStep | RmStep | RmdirStep | RunPHPStep | RunPHPWithOptionsStep | RunWpInstallationWizardStep | RunSqlStep<Resource> | SetPhpIniEntryStep | SetSiteOptionsStep | UnzipStep<Resource> | UpdateUserMetaStep | WriteFileStep<Resource> | WPCLIStep;
+export type GenericStep<Resource> = ActivatePluginStep | ActivateThemeStep | CpStep | DefineWpConfigConstsStep | DefineSiteUrlStep | EnableMultisiteStep | ImportWxrStep<Resource> | ImportWordPressFilesStep<Resource> | InstallPluginStep<Resource> | InstallThemeStep<Resource> | LoginStep | MkdirStep | MvStep | RequestStep | RmStep | RmdirStep | RunPHPStep | RunPHPWithOptionsStep | RunWpInstallationWizardStep | RunSqlStep<Resource> | SetSiteOptionsStep | UnzipStep<Resource> | UpdateUserMetaStep | WriteFileStep<Resource> | WPCLIStep;
 /**
  * Progress reporting details.
  */