@wp-playground/blueprints 0.1.61 → 0.3.0

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"];
-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>;
 }
@@ -33,5 +33,11 @@ export interface CompileBlueprintOptions {
  * @returns The compiled blueprint
  */
 export declare function compileBlueprint(blueprint: Blueprint, { progress, semaphore, onStepCompleted, }?: CompileBlueprintOptions): CompiledBlueprint;
+export declare function validateBlueprint(blueprintMaybe: object): {
+    valid: true;
+    errors?: undefined;
+} | {
+    valid: false;
+    errors: import("ajv").ErrorObject<string, Record<string, any>, unknown>[] | undefined;
+};
 export declare function runBlueprintSteps(compiledBlueprint: CompiledBlueprint, playground: UniversalPHP): Promise<void>;
-export {};

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

@@ -1,11 +1,25 @@
 import { StepHandler } from '.';
+/**
+ * @inheritDoc activatePlugin
+ * @example
+ *
+ * <code>
+ * {
+ * 		"step": "activatePlugin",
+ * 		"pluginName": "Gutenberg",
+ * 		"pluginPath": "/wordpress/wp-content/plugins/gutenberg"
+ * }
+ * </code>
+ */
 export interface ActivatePluginStep {
     step: 'activatePlugin';
+    /** Path to the plugin directory as absolute path (/wordpress/wp-content/plugins/plugin-name); or the plugin entry file relative to the plugins directory (plugin-name/plugin-name.php). */
     pluginPath: string;
+    /** Optional. Plugin name to display in the progress bar. */
     pluginName?: string;
 }
 /**
- * Activates a WordPress plugin in the Playground.
+ * Activates a WordPress plugin (if it's installed).
  *
  * @param playground The playground client.
  */

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

@@ -1,10 +1,25 @@
 import { StepHandler } from '.';
+/**
+ * @inheritDoc activateTheme
+ * @example
+ *
+ * <code>
+ * {
+ * 		"step": "activateTheme",
+ * 		"pluginName": "Storefront",
+ * 		"pluginPath": "/wordpress/wp-content/themes/storefront"
+ * }
+ * </code>
+ */
 export interface ActivateThemeStep {
     step: 'activateTheme';
+    /**
+     * The name of the theme folder inside wp-content/themes/
+     */
     themeFolderName: string;
 }
 /**
- * Activates a WordPress theme in the Playground.
+ * Activates a WordPress theme (if it's installed).
  *
  * @param playground The playground client.
  * @param themeFolderName The theme folder name.

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

@@ -1,4 +1,8 @@
+import { UniversalPHP } from '@php-wasm/universal';
 import { StepHandler } from '..';
+/**
+ * @private
+ */
 export interface ApplyWordPressPatchesStep {
     step: 'applyWordPressPatches';
     siteUrl?: string;
@@ -7,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/define-site-url.d.ts

@@ -1,10 +1,23 @@
 import { StepHandler } from '.';
+/**
+ * @inheritDoc defineSiteUrl
+ * @hasRunnableExample
+ * @example
+ *
+ * <code>
+ * {
+ * 		"step": "defineSiteUrl",
+ * 		"siteUrl": "https://playground.wordpress.net"
+ * }
+ * </code>
+ */
 export interface DefineSiteUrlStep {
     step: 'defineSiteUrl';
+    /** The URL */
     siteUrl: string;
 }
 /**
- * Sets site URL of the WordPress installation.
+ * Sets WP_HOME and WP_SITEURL constants for the WordPress installation.
  *
  * @param playground The playground client.
  * @param siteUrl

package/lib/steps/define-wp-config-consts.d.ts

@@ -1,7 +1,19 @@
 import { StepHandler } from '.';
 export declare const VFS_TMP_DIRECTORY = "/vfs-blueprints";
 /**
- * The step object for defining constants in the wp-config.php file of a WordPress installation.
+ * @inheritDoc defineWpConfigConsts
+ * @hasRunnableExample
+ * @example
+ *
+ * <code>
+ * {
+ * 		"step": "defineWpConfigConsts",
+ * 		"consts": {
+ *          "WP_DEBUG": true
+ *      },
+ *      "virtualize": true
+ * }
+ * </code>
  */
 export interface DefineWpConfigConstsStep {
     step: 'defineWpConfigConsts';
@@ -16,10 +28,9 @@ export interface DefineWpConfigConstsStep {
     virtualize?: boolean;
 }
 /**
- * Sets site URL of the WordPress installation.
+ * Defines the wp-config.php constants
  *
  * @param playground The playground client.
- * @param wpConfigConst An object containing the constants to be defined and the optional virtual file system configuration file path.
- * @returns Returns the virtual file system configuration file path.
+ * @param wpConfigConst
  */
 export declare const defineWpConfigConsts: StepHandler<DefineWpConfigConstsStep>;

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

@@ -9,20 +9,48 @@ import { StepHandler } from '.';
  * @param playground Playground client.
  */
 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';
+    /** The zip file containing the new WordPress site */
     fullSiteZip: ResourceType;
 }
 /**
- * Replace the current site with the contents of a full site zip file.
+ * Replace the current site with a site from the provided zip file.
+ * Remember to install the SQLite integration plugin in the zipped site:
+ * https://wordpress.org/plugins/sqlite-database-integration.
  *
  * @param playground Playground client.
  * @param fullSiteZip Zipped WordPress site.
  */
 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';
+    /** The zip file to extract */
     zipPath: string;
+    /** The path to extract the zip file to */
     extractToPath: string;
 }
 /**
@@ -52,8 +80,20 @@ export declare function exportWXR(playground: UniversalPHP): Promise<File>;
  * @returns WXZ 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';
+    /** The file to import */
     file: ResourceType;
 }
 /**

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/run-wp-installation-wizard.d.ts

@@ -1,4 +1,7 @@
 import { StepHandler } from '.';
+/**
+ * @private
+ */
 export interface RunWpInstallationWizardStep {
     step: 'runWpInstallationWizard';
     options: WordPressInstallationOptions;

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/site-data.d.ts

@@ -45,7 +45,9 @@ export declare const setSiteOptions: StepHandler<SetSiteOptionsStep>;
  */
 export interface UpdateUserMetaStep {
     step: 'updateUserMeta';
+    /** An object of user meta values to set, e.g. { "first_name": "John" } */
     meta: Record<string, unknown>;
+    /** User ID */
     userId: number;
 }
 /**

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.1.61",
+	"version": "0.3.0",
 	"exports": {
 		".": {
 			"import": "./index.js",
@@ -21,5 +21,9 @@
 		"access": "public",
 		"directory": "../../../dist/packages/playground/blueprints"
 	},
-	"gitHead": "f2cd7382004f7b003904b5db1d33d37fd2b1bfab"
+	"gitHead": "6890ff9243f9a10f0b86755fead101647a8c8535",
+	"engines": {
+		"node": ">=16.15.1",
+		"npm": ">=8.11.0"
+	}
 }

package/schema-readme.md

@@ -0,0 +1,9 @@
+The JSON schema stored in this directory is used to validate the Blueprints
+and is autogenerated from the Blueprints TypeScript types.
+
+Whenever the types are modified, the schema needs to be rebuilt using
+`nx build playground-blueprints` and then committed to the repository.
+
+Unfortunately, it is not auto-rebuilt in `npm run dev` mode as the
+`dts-bundle-generator` utility we use for type rollyps does not support
+watching for changes.