@wp-playground/blueprints 0.5.5 → 0.6.0

package/index.d.ts

@@ -182,17 +182,29 @@ declare class PHPResponse implements PHPResponseData {
 	get text(): string;
 }
 /**
- * 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.
  */
@@ -328,6 +340,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.
@@ -565,7 +582,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;
 export interface EventEmitter {
@@ -576,7 +593,7 @@ export 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";
@@ -641,6 +658,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;
 }
 export interface FileInfo {
 	key: string;
@@ -686,7 +708,7 @@ declare class Semaphore {
 	constructor({ concurrency }: SemaphoreOptions);
 	get running(): number;
 	acquire(): Promise<() => void>;
-	run<T>(fn: () => Promise<T>): Promise<T>;
+	run<T>(fn: () => T | Promise<T>): Promise<T>;
 }
 export declare const ResourceTypes: readonly [
 	"vfs",
@@ -1356,7 +1378,7 @@ export interface RunPHPStep {
 /**
  * Runs PHP code.
  */
-export declare const runPHP: StepHandler<RunPHPStep>;
+export declare const runPHP: StepHandler<RunPHPStep, Promise<PHPResponse>>;
 /**
  * @inheritDoc runPHP
  * @hasRunnableExample
@@ -1415,7 +1437,7 @@ export interface RequestStep {
 /**
  * Sends a HTTP request to the Playground.
  */
-export declare const request: StepHandler<RequestStep>;
+export declare const request: StepHandler<RequestStep, Promise<PHPResponse>>;
 /**
  * @inheritDoc writeFile
  * @hasRunnableExample
@@ -1522,15 +1544,23 @@ export declare const activateTheme: StepHandler<ActivateThemeStep>;
  * <code>
  * {
  * 		"step": "unzip",
- * 		"zipPath": "/wordpress/data.zip",
+ * 		"zipFile": {
+ * 			"resource": "vfs",
+ * 			"path": "/wordpress/data.zip"
+ * 		},
  * 		"extractToPath": "/wordpress"
  * }
  * </code>
  */
-export interface UnzipStep {
+export interface UnzipStep<ResourceType> {
 	step: "unzip";
 	/** The zip file to extract */
-	zipPath: string;
+	zipFile?: ResourceType;
+	/**
+	 * The path of the zip file to extract
+	 * @deprecated Use zipFile instead.
+	 */
+	zipPath?: string;
 	/** The path to extract the zip file to */
 	extractToPath: string;
 }
@@ -1541,7 +1571,7 @@ export interface UnzipStep {
  * @param zipPath The zip file to unzip.
  * @param extractTo The directory to extract the zip file to.
  */
-export declare const unzip: StepHandler<UnzipStep>;
+export declare const unzip: StepHandler<UnzipStep<File>>;
 /**
  * @inheritDoc importWordPressFiles
  * @example
@@ -1610,6 +1640,29 @@ export interface ImportFileStep<ResourceType> {
  * @param file The file to import.
  */
 export declare const importFile: StepHandler<ImportFileStep<File>>;
+/**
+ * @inheritDoc enableMultisite
+ * @hasRunnableExample
+ * @example
+ *
+ * <code>
+ * {
+ * 		"step": "enableMultisite",
+ * }
+ * </code>
+ */
+export interface EnableMultisiteStep {
+	step: "enableMultisite";
+}
+/**
+ * Defines constants in a wp-config.php file.
+ *
+ * This step can be called multiple times, and the constants will be merged.
+ *
+ * @param playground The playground client.
+ * @param enableMultisite
+ */
+export declare const enableMultisite: StepHandler<EnableMultisiteStep>;
 /**
  * Used by the export step to exclude the Playground-specific files
  * from the zip file. Keep it in sync with the list of files created
@@ -1627,7 +1680,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 | ApplyWordPressPatchesStep | CpStep | DefineWpConfigConstsStep | DefineSiteUrlStep | ImportFileStep<Resource> | ImportWordPressFilesStep<Resource> | InstallPluginStep<Resource> | InstallThemeStep<Resource> | LoginStep | MkdirStep | MvStep | RequestStep | RmStep | RmdirStep | RunPHPStep | RunPHPWithOptionsStep | RunWpInstallationWizardStep | RunSqlStep<Resource> | SetPhpIniEntryStep | SetSiteOptionsStep | UnzipStep | UpdateUserMetaStep | WriteFileStep<Resource>;
+export type GenericStep<Resource> = ActivatePluginStep | ActivateThemeStep | ApplyWordPressPatchesStep | CpStep | DefineWpConfigConstsStep | DefineSiteUrlStep | EnableMultisiteStep | ImportFileStep<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>;
 /**
  * Progress reporting details.
  */
@@ -1635,11 +1688,11 @@ export type StepProgress = {
 	tracker: ProgressTracker;
 	initialCaption?: string;
 };
-export type StepHandler<S extends GenericStep<File>> = (
+export type StepHandler<S extends GenericStep<File>, Return = any> = (
 /**
  * A PHP instance or Playground client.
  */
-php: UniversalPHP, args: Omit<S, "step">, progressArgs?: StepProgress) => any;
+php: UniversalPHP, args: Omit<S, "step">, progressArgs?: StepProgress) => Return;
 /**
  * Exports the WordPress database as a WXR file using
  * the core WordPress export tool.