@wp-playground/blueprints 0.2.0 → 0.3.1

package/lib/blueprint.d.ts

@@ -1,4 +1,4 @@
-import { SupportedPHPVersion } from '@php-wasm/universal';
+import { SupportedPHPExtensionBundle, SupportedPHPVersion } from '@php-wasm/universal';
 import { StepDefinition } from './steps';
 export interface Blueprint {
     /**
@@ -20,6 +20,10 @@ export interface Blueprint {
          */
         wp: string | 'latest';
     };
+    /**
+     * The PHP extensions to use.
+     */
+    phpExtensionBundles?: SupportedPHPExtensionBundle[];
     /**
      * The steps to run.
      */

package/lib/compile.d.ts

@@ -1,17 +1,17 @@
 import { ProgressTracker } from '@php-wasm/progress';
 import { Semaphore } from '@php-wasm/util';
-import { SupportedPHPVersion, UniversalPHP } from '@php-wasm/universal';
+import { SupportedPHPExtension, SupportedPHPVersion, UniversalPHP } from '@php-wasm/universal';
 import { StepDefinition } from './steps';
 import { Blueprint } from './blueprint';
 export type CompiledStep = (php: UniversalPHP) => Promise<void> | void;
-declare const supportedWordPressVersions: readonly ["6.2", "6.1", "6.0", "5.9", "nightly"];
-type supportedWordPressVersion = (typeof supportedWordPressVersions)[number];
 export interface CompiledBlueprint {
     /** The requested versions of PHP and WordPress for the blueprint */
     versions: {
         php: SupportedPHPVersion;
-        wp: supportedWordPressVersion;
+        wp: string;
     };
+    /** The requested PHP extensions to load */
+    phpExtensions: SupportedPHPExtension[];
     /** The compiled steps for the blueprint */
     run: (playground: UniversalPHP) => Promise<void>;
 }
@@ -41,4 +41,3 @@ export declare function validateBlueprint(blueprintMaybe: object): {
     errors: import("ajv").ErrorObject<string, Record<string, any>, unknown>[] | undefined;
 };
 export declare function runBlueprintSteps(compiledBlueprint: CompiledBlueprint, playground: UniversalPHP): Promise<void>;
-export {};

package/lib/resources.d.ts

@@ -146,7 +146,6 @@ export declare class UrlResource extends FetchResource {
     /** @inheritDoc */
     protected get caption(): string;
 }
-export declare function setPluginProxyURL(url: string): void;
 /**
  * A `Resource` that represents a WordPress core theme.
  */

package/lib/steps/activate-plugin.d.ts

@@ -1,6 +1,15 @@
 import { StepHandler } from '.';
 /**
  * @inheritDoc activatePlugin
+ * @example
+ *
+ * <code>
+ * {
+ * 		"step": "activatePlugin",
+ * 		"pluginName": "Gutenberg",
+ * 		"pluginPath": "/wordpress/wp-content/plugins/gutenberg"
+ * }
+ * </code>
  */
 export interface ActivatePluginStep {
     step: 'activatePlugin';

package/lib/steps/activate-theme.d.ts

@@ -1,6 +1,15 @@
 import { StepHandler } from '.';
 /**
  * @inheritDoc activateTheme
+ * @example
+ *
+ * <code>
+ * {
+ * 		"step": "activateTheme",
+ * 		"pluginName": "Storefront",
+ * 		"pluginPath": "/wordpress/wp-content/themes/storefront"
+ * }
+ * </code>
  */
 export interface ActivateThemeStep {
     step: 'activateTheme';

package/lib/steps/apply-wordpress-patches/index.d.ts

@@ -1,3 +1,4 @@
+import { UniversalPHP } from '@php-wasm/universal';
 import { StepHandler } from '..';
 /**
  * @private
@@ -10,5 +11,37 @@ export interface ApplyWordPressPatchesStep {
     patchSecrets?: boolean;
     disableSiteHealth?: boolean;
     disableWpNewBlogNotification?: boolean;
+    makeEditorFrameControlled?: boolean;
+    prepareForRunningInsideWebBrowser?: boolean;
 }
 export declare const applyWordPressPatches: StepHandler<ApplyWordPressPatchesStep>;
+/**
+ *
+ * Pair the site editor's nested iframe to the Service Worker.
+ *
+ * Without the patch below, the site editor initiates network requests that
+ * aren't routed through the service worker. That's a known browser issue:
+ *
+ * * https://bugs.chromium.org/p/chromium/issues/detail?id=880768
+ * * https://bugzilla.mozilla.org/show_bug.cgi?id=1293277
+ * * https://github.com/w3c/ServiceWorker/issues/765
+ *
+ * The problem with iframes using srcDoc and src="about:blank" as they
+ * fail to inherit the root site's service worker.
+ *
+ * Gutenberg loads the site editor using <iframe srcDoc="<!doctype html">
+ * to force the standards mode and not the quirks mode:
+ *
+ * https://github.com/WordPress/gutenberg/pull/38855
+ *
+ * This commit patches the site editor to achieve the same result via
+ * <iframe src="/doctype.html"> and a doctype.html file containing just
+ * `<!doctype html>`. This allows the iframe to inherit the service worker
+ * and correctly load all the css, js, fonts, images, and other assets.
+ *
+ * Ideally this issue would be fixed directly in Gutenberg and the patch
+ * below would be removed.
+ *
+ * See https://github.com/WordPress/wordpress-playground/issues/42 for more details
+ */
+export declare function makeEditorFrameControlled(php: UniversalPHP, wordpressPath: string, blockEditorScripts: string[]): Promise<void>;

package/lib/steps/cp.d.ts

@@ -0,0 +1,26 @@
+import { StepHandler } from '.';
+/**
+ * @inheritDoc cp
+ * @hasRunnableExample
+ * @landingPage /index2.php
+ * @example
+ *
+ * <code>
+ * {
+ * 		"step": "cp",
+ * 		"fromPath": "/wordpress/index.php",
+ * 		"toPath": "/wordpress/index2.php"
+ * }
+ * </code>
+ */
+export interface CpStep {
+    step: 'cp';
+    /** Source path */
+    fromPath: string;
+    /** Target path */
+    toPath: string;
+}
+/**
+ * Copies a file from one path to another.
+ */
+export declare const cp: StepHandler<CpStep>;

package/lib/steps/handlers.d.ts

@@ -1,7 +1,16 @@
 export { activatePlugin } from './activate-plugin';
 export { activateTheme } from './activate-theme';
 export { applyWordPressPatches } from './apply-wordpress-patches';
-export { rm, cp, mkdir, rmdir, mv, setPhpIniEntry, runPHP, runPHPWithOptions, request, writeFile, } from './client-methods';
+export { runPHP } from './run-php';
+export { runPHPWithOptions } from './run-php-with-options';
+export { setPhpIniEntry } from './set-php-ini-entry';
+export { request } from './request';
+export { cp } from './cp';
+export { mv } from './mv';
+export { rm } from './rm';
+export { mkdir } from './mkdir';
+export { rmdir } from './rmdir';
+export { writeFile } from './write-file';
 export { defineSiteUrl } from './define-site-url';
 export { importFile, unzip, replaceSite, zipEntireSite } from './import-export';
 export { installPlugin } from './install-plugin';

package/lib/steps/import-export.d.ts

@@ -11,6 +11,14 @@ import { StepHandler } from '.';
 export declare function zipEntireSite(playground: UniversalPHP): Promise<File>;
 /**
  * @inheritDoc replaceSite
+ * @example
+ *
+ * <code>
+ * {
+ * 		"step": "replaceSite",
+ * 		"fullSiteZip": "https://mysite.com/import.zip"
+ * }
+ * </code>
  */
 export interface ReplaceSiteStep<ResourceType> {
     step: 'replaceSite';
@@ -28,6 +36,15 @@ export interface ReplaceSiteStep<ResourceType> {
 export declare const replaceSite: StepHandler<ReplaceSiteStep<File>>;
 /**
  * @inheritDoc unzip
+ * @example
+ *
+ * <code>
+ * {
+ * 		"step": "unzip",
+ * 		"zipPath": "/wordpress/data.zip",
+ * 		"extractToPath": "/wordpress"
+ * }
+ * </code>
  */
 export interface UnzipStep {
     step: 'unzip';
@@ -65,6 +82,14 @@ export declare function exportWXR(playground: UniversalPHP): Promise<File>;
 export declare function exportWXZ(playground: UniversalPHP): Promise<File>;
 /**
  * @inheritDoc importFile
+ * @example
+ *
+ * <code>
+ * {
+ * 		"step": "importFile",
+ * 		"file": "https://mysite.com/import.WXR"
+ * }
+ * </code>
  */
 export interface ImportFileStep<ResourceType> {
     step: 'importFile';

package/lib/steps/index.d.ts

@@ -10,7 +10,16 @@ import { InstallThemeStep, InstallThemeOptions } from './install-theme';
 import { LoginStep } from './login';
 import { RunWpInstallationWizardStep, WordPressInstallationOptions } from './run-wp-installation-wizard';
 import { SetSiteOptionsStep, UpdateUserMetaStep } from './site-data';
-import { RmStep, CpStep, MkdirStep, RmdirStep, MvStep, SetPhpIniEntryStep, RunPHPStep, RunPHPWithOptionsStep, RequestStep, WriteFileStep } from './client-methods';
+import { RmStep } from './rm';
+import { CpStep } from './cp';
+import { RmdirStep } from './rmdir';
+import { MkdirStep } from './mkdir';
+import { MvStep } from './mv';
+import { SetPhpIniEntryStep } from './set-php-ini-entry';
+import { RunPHPStep } from './run-php';
+import { RunPHPWithOptionsStep } from './run-php-with-options';
+import { RequestStep } from './request';
+import { WriteFileStep } from './write-file';
 import { DefineWpConfigConstsStep } from './define-wp-config-consts';
 import { ActivateThemeStep } from './activate-theme';
 export type Step = GenericStep<FileReference>;

package/lib/steps/mkdir.d.ts

@@ -0,0 +1,22 @@
+import { StepHandler } from '.';
+/**
+ * @inheritDoc mkdir
+ * @hasRunnableExample
+ * @example
+ *
+ * <code>
+ * {
+ * 		"step": "mkdir",
+ * 		"path": "/wordpress/my-new-folder"
+ * }
+ * </code>
+ */
+export interface MkdirStep {
+    step: 'mkdir';
+    /** The path of the directory you want to create */
+    path: string;
+}
+/**
+ * Creates a directory at the specified path.
+ */
+export declare const mkdir: StepHandler<MkdirStep>;

package/lib/steps/mv.d.ts

@@ -0,0 +1,26 @@
+import { StepHandler } from '.';
+/**
+ * @inheritDoc mv
+ * @hasRunnableExample
+ * @landingPage /index2.php
+ * @example
+ *
+ * <code>
+ * {
+ * 		"step": "mv",
+ * 		"fromPath": "/wordpress/index.php",
+ * 		"toPath": "/wordpress/index2.php"
+ * }
+ * </code>
+ */
+export interface MvStep {
+    step: 'mv';
+    /** Source path */
+    fromPath: string;
+    /** Target path */
+    toPath: string;
+}
+/**
+ * Moves a file or directory from one path to another.
+ */
+export declare const mv: StepHandler<MvStep>;

package/lib/steps/request.d.ts

@@ -0,0 +1,33 @@
+import { PHPRequest } from '@php-wasm/universal';
+import { StepHandler } from '.';
+/**
+ * @inheritDoc request
+ * @needsLogin
+ * @hasRunnableExample
+ * @example
+ *
+ * <code>
+ * {
+ * 		"step": "request",
+ * 		"request": {
+ * 			"method": "POST",
+ * 			"url": "/wp-admin/admin-ajax.php",
+ * 			"formData": {
+ * 				"action": "my_action",
+ * 				"foo": "bar"
+ * 			}
+ * 		}
+ * }
+ * </code>
+ */
+export interface RequestStep {
+    step: 'request';
+    /**
+     * Request details (See /wordpress-playground/api/universal/interface/PHPRequest)
+     */
+    request: PHPRequest;
+}
+/**
+ * Sends a HTTP request to the Playground.
+ */
+export declare const request: StepHandler<RequestStep>;

package/lib/steps/rm.d.ts

@@ -0,0 +1,23 @@
+import { StepHandler } from '.';
+/**
+ * @inheritDoc rm
+ * @hasRunnableExample
+ * @landingPage /index.php
+ * @example
+ *
+ * <code>
+ * {
+ * 		"step": "rm",
+ * 		"path": "/wordpress/index.php"
+ * }
+ * </code>
+ */
+export interface RmStep {
+    step: 'rm';
+    /** The path to remove */
+    path: string;
+}
+/**
+ * Removes a file at the specified path.
+ */
+export declare const rm: StepHandler<RmStep>;

package/lib/steps/rmdir.d.ts

@@ -0,0 +1,23 @@
+import { StepHandler } from '.';
+/**
+ * @inheritDoc rmdir
+ * @hasRunnableExample
+ * @landingPage /wp-admin/
+ * @example
+ *
+ * <code>
+ * {
+ * 		"step": "rmdir",
+ * 		"path": "/wordpress/wp-admin"
+ * }
+ * </code>
+ */
+export interface RmdirStep {
+    step: 'rmdir';
+    /** The path to remove */
+    path: string;
+}
+/**
+ * Removes a directory at the specified path.
+ */
+export declare const rmdir: StepHandler<RmdirStep>;

package/lib/steps/run-php-with-options.d.ts

@@ -0,0 +1,30 @@
+import { StepHandler } from '.';
+import { PHPRunOptions } from '@php-wasm/universal';
+/**
+ * @inheritDoc runPHP
+ * @hasRunnableExample
+ * @example
+ *
+ * <code>
+ * {
+ * 		"step": "runPHP",
+ * 		"options": {
+ * 			"code": "<?php echo $_SERVER['CONTENT_TYPE']; ?>",
+ * 			"headers": {
+ * 				"Content-type": "text/plain"
+ * 			}
+ * 		}
+ * }
+ * </code>
+ */
+export interface RunPHPWithOptionsStep {
+    step: 'runPHPWithOptions';
+    /**
+     * Run options (See /wordpress-playground/api/universal/interface/PHPRunOptions)
+     */
+    options: PHPRunOptions;
+}
+/**
+ * Runs PHP code with the given options.
+ */
+export declare const runPHPWithOptions: StepHandler<RunPHPWithOptionsStep>;

package/lib/steps/run-php.d.ts

@@ -0,0 +1,23 @@
+import { StepHandler } from '.';
+/**
+ * @inheritDoc runPHP
+ * @hasRunnableExample
+ * @example
+ *
+ * <code>
+ * {
+ * 		"step": "runPHP",
+ * 		"code": "<?php require_once 'wordpress/wp-load.php'; wp_insert_post(array('post_title' => 'wp-load.php required for WP functionality', 'post_status' => 'publish')); ?>"
+ * }
+ * </code>
+ */
+export interface RunPHPStep {
+    /** The step identifier. */
+    step: 'runPHP';
+    /** The PHP code to run. */
+    code: string;
+}
+/**
+ * Runs PHP code.
+ */
+export declare const runPHP: StepHandler<RunPHPStep>;

package/lib/steps/set-php-ini-entry.d.ts

@@ -0,0 +1,25 @@
+import { StepHandler } from '.';
+/**
+ * @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>;

package/lib/steps/write-file.d.ts

@@ -0,0 +1,26 @@
+import { StepHandler } from '.';
+/**
+ * @inheritDoc writeFile
+ * @hasRunnableExample
+ * @landingPage /test.php
+ * @example
+ *
+ * <code>
+ * {
+ * 		"step": "writeFile",
+ * 		"path": "/wordpress/test.php",
+ * 		"data": "<?php echo 'Hello World!'; ?>"
+ * }
+ * </code>
+ */
+export interface WriteFileStep<ResourceType> {
+    step: 'writeFile';
+    /** The path of the file to write to */
+    path: string;
+    /** The data to write */
+    data: ResourceType | string | Uint8Array;
+}
+/**
+ * Writes data to a file at the specified path.
+ */
+export declare const writeFile: StepHandler<WriteFileStep<File>>;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wp-playground/blueprints",
-	"version": "0.2.0",
+	"version": "0.3.1",
 	"exports": {
 		".": {
 			"import": "./index.js",
@@ -21,7 +21,7 @@
 		"access": "public",
 		"directory": "../../../dist/packages/playground/blueprints"
 	},
-	"gitHead": "cd4062de74f7f18058d3f962e124d0fdff78b5a7",
+	"gitHead": "73b285f8b496c7442474fd7325b3f6b1287cbf95",
 	"engines": {
 		"node": ">=16.15.1",
 		"npm": ">=8.11.0"