@wp-playground/blueprints 0.1.28 → 0.1.30

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

@@ -1,6 +1,6 @@
 import { PHPResponse, UniversalPHP } from '@php-wasm/universal';
 import { phpVars } from '@php-wasm/util';
-import { BaseStep } from '.';
+import { StepHandler } from '.';
 
 // @ts-ignore
 import migrationsPHPCode from './migration.php?raw';
@@ -9,17 +9,6 @@ import migrationsPHPCode from './migration.php?raw';
  * Full site export support:
  */
 
-export interface ReplaceSiteStep<ResourceType> extends BaseStep {
-	step: 'replaceSite';
-	fullSiteZip: ResourceType;
-}
-
-export interface UnzipStep extends BaseStep {
-	step: 'unzip';
-	zipPath: string;
-	extractToPath: string;
-}
-
 /**
  * Export the current site as a zip file.
  *
@@ -44,13 +33,21 @@ export async function zipEntireSite(playground: UniversalPHP) {
 	return new File([fileBuffer], zipName);
 }
 
+export interface ReplaceSiteStep<ResourceType> {
+	step: 'replaceSite';
+	fullSiteZip: ResourceType;
+}
+
 /**
  * Replace the current site with the contents of a full site zip file.
  *
  * @param playground Playground client.
  * @param fullSiteZip Zipped WordPress site.
  */
-export async function replaceSite(playground: UniversalPHP, fullSiteZip: File) {
+export const replaceSite: StepHandler<ReplaceSiteStep<File>> = async (
+	playground,
+	{ fullSiteZip }
+) => {
 	const zipPath = '/import.zip';
 	await playground.writeFile(
 		zipPath,
@@ -61,7 +58,7 @@ export async function replaceSite(playground: UniversalPHP, fullSiteZip: File) {
 	const documentRoot = await playground.documentRoot;
 
 	await playground.rmdir(documentRoot);
-	await unzip(playground, zipPath, '/');
+	await unzip(playground, { zipPath, extractToPath: '/' });
 
 	const js = phpVars({ absoluteUrl });
 	await updateFile(
@@ -75,6 +72,12 @@ export async function replaceSite(playground: UniversalPHP, fullSiteZip: File) {
 			}
 			?>${contents}`
 	);
+};
+
+export interface UnzipStep {
+	step: 'unzip';
+	zipPath: string;
+	extractToPath: string;
 }
 
 /**
@@ -84,17 +87,19 @@ export async function replaceSite(playground: UniversalPHP, fullSiteZip: File) {
  * @param zipPath The zip file to unzip.
  * @param extractTo The directory to extract the zip file to.
  */
-export async function unzip(
-	playground: UniversalPHP,
-	zipPath: string,
-	extractTo: string
-) {
+export const unzip: StepHandler<UnzipStep> = async (
+	playground,
+	{ zipPath, extractToPath }
+) => {
 	const js = phpVars({
 		zipPath,
-		extractTo,
+		extractToPath,
 	});
-	await phpMigration(playground, `unzip(${js.zipPath}, ${js.extractTo});`);
-}
+	await phpMigration(
+		playground,
+		`unzip(${js.zipPath}, ${js.extractToPath});`
+	);
+};
 
 /**
  * WXR and WXZ files support:
@@ -128,7 +133,7 @@ export async function exportWXZ(playground: UniversalPHP) {
 	return new File([databaseExportResponse.bytes], 'export.wxz');
 }
 
-export interface ImportFileStep<ResourceType> extends BaseStep {
+export interface ImportFileStep<ResourceType> {
 	step: 'importFile';
 	file: ResourceType;
 }
@@ -141,7 +146,10 @@ export interface ImportFileStep<ResourceType> extends BaseStep {
  * @param playground Playground client.
  * @param file The file to import.
  */
-export async function submitImporterForm(playground: UniversalPHP, file: File) {
+export const importFile: StepHandler<ImportFileStep<File>> = async (
+	playground,
+	{ file }
+) => {
 	const importerPageOneResponse = await playground.request({
 		url: '/wp-admin/admin.php?import=wordpress',
 	});
@@ -177,12 +185,12 @@ export async function submitImporterForm(playground: UniversalPHP, file: File) {
 		}
 	}
 
-	return await playground.request({
+	await playground.request({
 		url: importForm.action,
 		method: 'POST',
 		formData: data,
 	});
-}
+};
 
 function DOM(response: PHPResponse) {
 	return new DOMParser().parseFromString(response.text, 'text/html');

package/src/lib/steps/index.ts

@@ -1,38 +1,8 @@
-export {
-	zipEntireSite,
-	exportWXR,
-	exportWXZ,
-	replaceSite,
-	submitImporterForm,
-} from './import-export';
-export { login } from './login';
-export { installTheme } from './install-theme';
-export type { InstallThemeOptions } from './install-theme';
-export { installPlugin } from './install-plugin';
-export type { InstallPluginOptions } from './install-plugin';
-export { activatePlugin } from './activate-plugin';
-export { setSiteOptions, updateUserMeta } from './site-data';
-export type { SiteOptions, UserMeta } from './site-data';
-export { defineSiteUrl } from './define-site-url';
-export { applyWordPressPatches } from './apply-wordpress-patches';
-export type { PatchOptions } from './apply-wordpress-patches';
-export { runWpInstallationWizard } from './run-wp-installation-wizard';
-export type { WordPressInstallationOptions } from './run-wp-installation-wizard';
-
+import { ProgressTracker } from '@php-wasm/progress';
+import { UniversalPHP } from '@php-wasm/universal';
+import { FileReference } from '../resources';
 import { ActivatePluginStep } from './activate-plugin';
 import { ApplyWordPressPatchesStep } from './apply-wordpress-patches';
-import {
-	RunPHPStep,
-	RunPHPWithOptionsStep,
-	SetPhpIniEntryStep,
-	RequestStep,
-	CpStep,
-	RmStep,
-	RmdirStep,
-	MvStep,
-	MkdirStep,
-	WriteFileStep,
-} from './client-methods';
 import { DefineSiteUrlStep } from './define-site-url';
 import { ImportFileStep, ReplaceSiteStep, UnzipStep } from './import-export';
 import { InstallPluginStep } from './install-plugin';
@@ -40,59 +10,56 @@ import { InstallThemeStep } from './install-theme';
 import { LoginStep } from './login';
 import { RunWpInstallationWizardStep } from './run-wp-installation-wizard';
 import { SetSiteOptionsStep, UpdateUserMetaStep } from './site-data';
-export interface BaseStep {
-	step: string;
+import {
+	RmStep,
+	CpStep,
+	MkdirStep,
+	RmdirStep,
+	MvStep,
+	SetPhpIniEntryStep,
+	RunPHPStep,
+	RunPHPWithOptionsStep,
+	RequestStep,
+	WriteFileStep,
+} from './client-methods';
+
+export type Step = GenericStep<FileReference>;
+export type StepDefinition = Step & {
 	progress?: {
 		weight?: number;
 		caption?: string;
 	};
-}
+};
 
-export type Step<ResourceType> =
-	| InstallPluginStep<ResourceType>
-	| InstallThemeStep<ResourceType>
-	| LoginStep
-	| ImportFileStep<ResourceType>
+export type GenericStep<Resource> =
 	| ActivatePluginStep
-	| ReplaceSiteStep<ResourceType>
-	| UnzipStep
-	| DefineSiteUrlStep
 	| ApplyWordPressPatchesStep
-	| RunWpInstallationWizardStep
-	| SetSiteOptionsStep
-	| UpdateUserMetaStep
-	| RunPHPStep
-	| RunPHPWithOptionsStep
-	| SetPhpIniEntryStep
-	| RequestStep
 	| CpStep
+	| DefineSiteUrlStep
+	| ImportFileStep<Resource>
+	| InstallPluginStep<Resource>
+	| InstallThemeStep<Resource>
+	| LoginStep
+	| MkdirStep
+	| MvStep
+	| RequestStep
+	| ReplaceSiteStep<Resource>
 	| RmStep
 	| RmdirStep
-	| MvStep
-	| MkdirStep
-	| WriteFileStep<ResourceType>;
+	| RunPHPStep
+	| RunPHPWithOptionsStep
+	| RunWpInstallationWizardStep
+	| SetPhpIniEntryStep
+	| SetSiteOptionsStep
+	| UnzipStep
+	| UpdateUserMetaStep
+	| WriteFileStep<Resource>;
 
-export type {
-	InstallPluginStep,
-	InstallThemeStep,
-	LoginStep,
-	ImportFileStep,
-	ActivatePluginStep,
-	ReplaceSiteStep,
-	UnzipStep,
-	DefineSiteUrlStep,
-	ApplyWordPressPatchesStep,
-	RunWpInstallationWizardStep,
-	SetSiteOptionsStep,
-	UpdateUserMetaStep,
-	RunPHPStep,
-	RunPHPWithOptionsStep,
-	SetPhpIniEntryStep,
-	RequestStep,
-	CpStep,
-	RmStep,
-	RmdirStep,
-	MvStep,
-	MkdirStep,
-	WriteFileStep,
-};
+export type StepHandler<S extends GenericStep<File>> = (
+	php: UniversalPHP,
+	args: Omit<S, 'step'>,
+	progressArgs?: {
+		tracker: ProgressTracker;
+		initialCaption?: string;
+	}
+) => any;

package/src/lib/steps/install-plugin.ts

@@ -1,8 +1,8 @@
 import { UniversalPHP } from '@php-wasm/universal';
-import { BaseStep } from '.';
-import { asDOM } from './common';
+import { StepHandler } from '.';
+import { asDOM, zipNameToHumanName } from './common';
 
-export interface InstallPluginStep<ResourceType> extends BaseStep {
+export interface InstallPluginStep<ResourceType> {
 	step: 'installPlugin';
 	pluginZipFile: ResourceType;
 	options?: InstallPluginOptions;
@@ -24,105 +24,122 @@ export interface InstallPluginOptions {
  * @param pluginZipFile The plugin zip file.
  * @param options Optional. Set `activate` to false if you don't want to activate the plugin.
  */
-export async function installPlugin(
-	playground: UniversalPHP,
-	pluginZipFile: File,
-	options: InstallPluginOptions = {}
-) {
-	const activate = 'activate' in options ? options.activate : true;
-
-	// Upload it to WordPress
-	const pluginForm = await playground.request({
-		url: '/wp-admin/plugin-install.php?tab=upload',
-	});
-	const pluginFormPage = asDOM(pluginForm);
-	const pluginFormData = new FormData(
-		pluginFormPage.querySelector('.wp-upload-form')! as HTMLFormElement
-	) as any;
-	// eslint-disable-next-line @typescript-eslint/no-unused-vars
-	const { pluginzip, ...postData } = Object.fromEntries(
-		pluginFormData.entries()
+export const installPlugin: StepHandler<InstallPluginStep<File>> = async (
+	playground,
+	{ pluginZipFile, options = {} },
+	progress?
+) => {
+	progress?.tracker.setCaption(
+		`Installing the ${zipNameToHumanName(pluginZipFile?.name)} plugin`
 	);
+	try {
+		const activate = 'activate' in options ? options.activate : true;
 
-	const pluginInstalledResponse = await playground.request({
-		url: '/wp-admin/update.php?action=upload-plugin',
-		method: 'POST',
-		formData: postData,
-		files: { pluginzip: pluginZipFile },
-	});
+		// Upload it to WordPress
+		const pluginForm = await playground.request({
+			url: '/wp-admin/plugin-install.php?tab=upload',
+		});
+		const pluginFormPage = asDOM(pluginForm);
+		const pluginFormData = new FormData(
+			pluginFormPage.querySelector('.wp-upload-form')! as HTMLFormElement
+		) as any;
+		// eslint-disable-next-line @typescript-eslint/no-unused-vars
+		const { pluginzip, ...postData } = Object.fromEntries(
+			pluginFormData.entries()
+		);
 
-	// Activate if needed
-	if (activate) {
-		const pluginInstalledPage = asDOM(pluginInstalledResponse);
-		const activateButtonHref = pluginInstalledPage
-			.querySelector('#wpbody-content .button.button-primary')!
-			.attributes.getNamedItem('href')!.value;
-		const activatePluginUrl = new URL(
-			activateButtonHref,
-			await playground.pathToInternalUrl('/wp-admin/')
-		).toString();
-		await playground.request({
-			url: activatePluginUrl,
+		const pluginInstalledResponse = await playground.request({
+			url: '/wp-admin/update.php?action=upload-plugin',
+			method: 'POST',
+			formData: postData,
+			files: { pluginzip: pluginZipFile },
 		});
-	}
 
-	/**
-	 * 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
-	 */
-	async function updateFile(
-		path: string,
-		callback: (contents: string) => string
-	) {
-		return await playground.writeFile(
-			path,
-			callback(await playground.readFileAsText(path))
-		);
-	}
-	if (
-		(await playground.isDir('/wordpress/wp-content/plugins/gutenberg')) &&
-		!(await playground.fileExists('/wordpress/.gutenberg-patched'))
-	) {
-		await playground.writeFile('/wordpress/.gutenberg-patched', '1');
-		await updateFile(
-			`/wordpress/wp-content/plugins/gutenberg/build/block-editor/index.js`,
-			(contents) =>
-				contents.replace(
-					/srcDoc:("[^"]+"|[^,]+)/g,
-					'src:"/wp-includes/empty.html"'
-				)
-		);
-		await updateFile(
-			`/wordpress/wp-content/plugins/gutenberg/build/block-editor/index.min.js`,
-			(contents) =>
-				contents.replace(
-					/srcDoc:("[^"]+"|[^,]+)/g,
-					'src:"/wp-includes/empty.html"'
-				)
+		// Activate if needed
+		if (activate) {
+			const pluginInstalledPage = asDOM(pluginInstalledResponse);
+			const activateButtonHref = pluginInstalledPage
+				.querySelector('#wpbody-content .button.button-primary')!
+				.attributes.getNamedItem('href')!.value;
+			const activatePluginUrl = new URL(
+				activateButtonHref,
+				await playground.pathToInternalUrl('/wp-admin/')
+			).toString();
+			await playground.request({
+				url: activatePluginUrl,
+			});
+		}
+
+		/**
+		 * 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
+		 */
+		if (
+			(await playground.isDir(
+				'/wordpress/wp-content/plugins/gutenberg'
+			)) &&
+			!(await playground.fileExists('/wordpress/.gutenberg-patched'))
+		) {
+			await playground.writeFile('/wordpress/.gutenberg-patched', '1');
+			await updateFile(
+				playground,
+				`/wordpress/wp-content/plugins/gutenberg/build/block-editor/index.js`,
+				(contents) =>
+					contents.replace(
+						/srcDoc:("[^"]+"|[^,]+)/g,
+						'src:"/wp-includes/empty.html"'
+					)
+			);
+			await updateFile(
+				playground,
+				`/wordpress/wp-content/plugins/gutenberg/build/block-editor/index.min.js`,
+				(contents) =>
+					contents.replace(
+						/srcDoc:("[^"]+"|[^,]+)/g,
+						'src:"/wp-includes/empty.html"'
+					)
+			);
+		}
+	} catch (error) {
+		console.error(
+			`Proceeding without the ${pluginZipFile.name} theme. Could not install it in wp-admin. ` +
+				`The original error was: ${error}`
 		);
+		console.error(error);
 	}
+};
+
+async function updateFile(
+	playground: UniversalPHP,
+	path: string,
+	callback: (contents: string) => string
+) {
+	return await playground.writeFile(
+		path,
+		callback(await playground.readFileAsText(path))
+	);
 }

package/src/lib/steps/install-theme.ts

@@ -1,8 +1,7 @@
-import { UniversalPHP } from '@php-wasm/universal';
-import { BaseStep } from '.';
-import { asDOM } from './common';
+import { StepHandler } from '.';
+import { asDOM, zipNameToHumanName } from './common';
 
-export interface InstallThemeStep<ResourceType> extends BaseStep {
+export interface InstallThemeStep<ResourceType> {
 	step: 'installTheme';
 	themeZipFile: ResourceType;
 	options?: InstallThemeOptions;
@@ -24,66 +23,77 @@ export interface InstallThemeOptions {
  * @param themeZipFile The theme zip file.
  * @param options Optional. Set `activate` to false if you don't want to activate the theme.
  */
-export async function installTheme(
-	playground: UniversalPHP,
-	themeZipFile: File,
-	options: InstallThemeOptions = {}
-) {
-	const activate = 'activate' in options ? options.activate : true;
-
-	// Upload it to WordPress
-	const themeForm = await playground.request({
-		url: '/wp-admin/theme-install.php',
-	});
-	const themeFormPage = asDOM(themeForm);
-	const themeFormData = new FormData(
-		themeFormPage.querySelector('.wp-upload-form')! as HTMLFormElement
-	) as any;
-	// eslint-disable-next-line @typescript-eslint/no-unused-vars
-	const { themezip, ...postData } = Object.fromEntries(
-		themeFormData.entries()
+export const installTheme: StepHandler<InstallThemeStep<File>> = async (
+	playground,
+	{ themeZipFile, options = {} },
+	progress
+) => {
+	progress?.tracker.setCaption(
+		`Installing the ${zipNameToHumanName(themeZipFile.name)} theme`
 	);
+	try {
+		const activate = 'activate' in options ? options.activate : true;
 
-	const themeInstalledResponse = await playground.request({
-		url: '/wp-admin/update.php?action=upload-theme',
-		method: 'POST',
-		formData: postData,
-		files: { themezip: themeZipFile },
-	});
+		// Upload it to WordPress
+		const themeForm = await playground.request({
+			url: '/wp-admin/theme-install.php',
+		});
+		const themeFormPage = asDOM(themeForm);
+		const themeFormData = new FormData(
+			themeFormPage.querySelector('.wp-upload-form')! as HTMLFormElement
+		) as any;
+		// eslint-disable-next-line @typescript-eslint/no-unused-vars
+		const { themezip, ...postData } = Object.fromEntries(
+			themeFormData.entries()
+		);
 
-	// Activate if needed
-	if (activate) {
-		const themeInstalledPage = asDOM(themeInstalledResponse);
+		const themeInstalledResponse = await playground.request({
+			url: '/wp-admin/update.php?action=upload-theme',
+			method: 'POST',
+			formData: postData,
+			files: { themezip: themeZipFile },
+		});
 
-		const messageContainer = themeInstalledPage.querySelector(
-			'#wpbody-content > .wrap'
-		);
-		if (
-			messageContainer?.textContent?.includes(
-				'Theme installation failed.'
-			)
-		) {
-			console.error(messageContainer?.textContent);
-			return;
-		}
+		// Activate if needed
+		if (activate) {
+			const themeInstalledPage = asDOM(themeInstalledResponse);
 
-		const activateButton = themeInstalledPage.querySelector(
-			'#wpbody-content .activatelink, ' +
-				'.update-from-upload-actions .button.button-primary'
-		);
-		if (!activateButton) {
-			console.error('The "activate" button was not found.');
-			return;
-		}
+			const messageContainer = themeInstalledPage.querySelector(
+				'#wpbody-content > .wrap'
+			);
+			if (
+				messageContainer?.textContent?.includes(
+					'Theme installation failed.'
+				)
+			) {
+				console.error(messageContainer?.textContent);
+				return;
+			}
 
-		const activateButtonHref =
-			activateButton.attributes.getNamedItem('href')!.value;
-		const activateThemeUrl = new URL(
-			activateButtonHref,
-			await playground.pathToInternalUrl('/wp-admin/')
-		).toString();
-		await playground.request({
-			url: activateThemeUrl,
-		});
+			const activateButton = themeInstalledPage.querySelector(
+				'#wpbody-content .activatelink, ' +
+					'.update-from-upload-actions .button.button-primary'
+			);
+			if (!activateButton) {
+				console.error('The "activate" button was not found.');
+				return;
+			}
+
+			const activateButtonHref =
+				activateButton.attributes.getNamedItem('href')!.value;
+			const activateThemeUrl = new URL(
+				activateButtonHref,
+				await playground.pathToInternalUrl('/wp-admin/')
+			).toString();
+			await playground.request({
+				url: activateThemeUrl,
+			});
+		}
+	} catch (error) {
+		console.error(
+			`Proceeding without the ${themeZipFile.name} theme. Could not install it in wp-admin. ` +
+				`The original error was: ${error}`
+		);
+		console.error(error);
 	}
-}
+};