@wordpress/env 10.38.1-next.v.0 → 11.0.0

package/lib/{init-config.js → runtime/docker/init-config.js}

@@ -10,11 +10,11 @@ const yaml = require( 'js-yaml' );
 /**
  * Internal dependencies
  */
-const { loadConfig, ValidationError } = require( './config' );
+const { loadConfig, ValidationError } = require( '../../config' );
 const buildDockerComposeConfig = require( './build-docker-compose-config' );
 
 /**
- * @typedef {import('./config').WPConfig} WPConfig
+ * @typedef {import('../../config').WPConfig} WPConfig
  */
 
 /**
@@ -22,16 +22,17 @@ const buildDockerComposeConfig = require( './build-docker-compose-config' );
  * ./.wp-env.json, creates ~/.wp-env, ~/.wp-env/docker-compose.yml, and
  * ~/.wp-env/Dockerfile.
  *
- * @param {Object}  options
- * @param {Object}  options.spinner      A CLI spinner which indicates progress.
- * @param {boolean} options.debug        True if debug mode is enabled.
- * @param {string}  options.xdebug       The Xdebug mode to set. Defaults to "off".
- * @param {string}  options.spx          The SPX mode to set. Defaults to "off".
- * @param {boolean} options.writeChanges If true, writes the parsed config to the
- *                                       required docker files like docker-compose
- *                                       and Dockerfile. By default, this is false
- *                                       and only the `start` command writes any
- *                                       changes.
+ * @param {Object}      options
+ * @param {Object}      options.spinner          A CLI spinner which indicates progress.
+ * @param {boolean}     options.debug            True if debug mode is enabled.
+ * @param {string}      options.xdebug           The Xdebug mode to set. Defaults to "off".
+ * @param {string}      options.spx              The SPX mode to set. Defaults to "off".
+ * @param {boolean}     options.writeChanges     If true, writes the parsed config to the
+ *                                               required docker files like docker-compose
+ *                                               and Dockerfile. By default, this is false
+ *                                               and only the `start` command writes any
+ *                                               changes.
+ * @param {string|null} options.customConfigPath Path to a custom .wp-env.json configuration file.
  * @return {WPConfig} The-env config object.
  */
 module.exports = async function initConfig( {
@@ -40,8 +41,9 @@ module.exports = async function initConfig( {
 	xdebug = 'off',
 	spx = 'off',
 	writeChanges = false,
+	customConfigPath = null,
 } ) {
-	const config = await loadConfig( path.resolve( '.' ) );
+	const config = await loadConfig( path.resolve( '.' ), customConfigPath );
 	config.debug = debug;
 
 	// Adding this to the config allows the start command to understand that the
@@ -87,10 +89,16 @@ module.exports = async function initConfig( {
 			yaml.dump( dockerComposeConfig )
 		);
 
-		// Write four Dockerfiles for each service we provided.
+		// Write Dockerfiles for each service we provided.
 		// (WordPress and CLI services, then a development and test environment for each.)
 		for ( const imageType of [ 'WordPress', 'CLI' ] ) {
 			for ( const envType of [ 'development', 'tests' ] ) {
+				if (
+					envType === 'tests' &&
+					config.testsEnvironment === false
+				) {
+					continue;
+				}
 				await writeFile(
 					path.resolve(
 						config.workDirectoryPath,

package/lib/runtime/docker/wordpress.js

@@ -0,0 +1,309 @@
+'use strict';
+/**
+ * External dependencies
+ */
+const util = require( 'util' );
+const { v2: dockerCompose } = require( 'docker-compose' );
+
+/**
+ * Promisified dependencies
+ */
+const copyDir = util.promisify( require( 'copy-dir' ) );
+
+/**
+ * Internal dependencies
+ */
+const { readWordPressVersion } = require( '../../wordpress' );
+
+/**
+ * @typedef {import('../../config').WPConfig} WPConfig
+ * @typedef {import('../../config').WPEnvironmentConfig} WPEnvironmentConfig
+ * @typedef {import('../../config').WPSource} WPSource
+ * @typedef {'development'|'tests'} WPEnvironment
+ * @typedef {'development'|'tests'|'all'} WPEnvironmentSelection
+ */
+
+/**
+ * Utility function to check if a WordPress version is lower than another version.
+ *
+ * This is a non-comprehensive check only intended for this usage, to avoid pulling in a full semver library.
+ * It only considers the major and minor portions of the version and ignores the rest. Additionally, it assumes that
+ * the minor version is always a single digit (i.e. 0-9).
+ *
+ * Do not use this function for general version comparison, as it will not work for all cases.
+ *
+ * @param {string} version        The version to check.
+ * @param {string} compareVersion The compare version to check whether the version is lower than.
+ * @return {boolean} True if the version is lower than the compare version, false otherwise.
+ */
+function isWPMajorMinorVersionLower( version, compareVersion ) {
+	const versionNumber = Number.parseFloat(
+		version.match( /^[0-9]+(\.[0-9]+)?/ )[ 0 ]
+	);
+	const compareVersionNumber = Number.parseFloat(
+		compareVersion.match( /^[0-9]+(\.[0-9]+)?/ )[ 0 ]
+	);
+
+	return versionNumber < compareVersionNumber;
+}
+
+/**
+ * Configures WordPress for the given environment by installing WordPress,
+ * activating all plugins, and activating the first theme. These steps are
+ * performed sequentially so as to not overload the WordPress instance.
+ *
+ * @param {WPEnvironment} environment The environment to configure. Either 'development' or 'tests'.
+ * @param {WPConfig}      config      The wp-env config object.
+ * @param {Object}        spinner     A CLI spinner which indicates progress.
+ */
+async function configureWordPress( environment, config, spinner ) {
+	let wpVersion = '';
+	try {
+		wpVersion = await readWordPressVersion(
+			config.env[ environment ].coreSource,
+			spinner,
+			config.debug
+		);
+	} catch ( err ) {
+		// Ignore error.
+	}
+
+	// Create a project-specific wp-cli configuration, important for the `rewrite` command.
+	// Don't overwrite existing configuration.
+	const cliConfigCommand = `[ -f /var/www/html/wp-cli.yml ] || (
+		exec > /var/www/html/wp-cli.yml
+		echo "apache_modules:"
+		echo "  - mod_rewrite"
+	)`;
+
+	const isMultisite = config.env[ environment ].multisite;
+
+	const installMethod = isMultisite ? 'multisite-install' : 'install';
+	const installCommand = `wp core ${ installMethod } --url="${ config.env[ environment ].config.WP_SITEURL }" --title="${ config.name }" --admin_user=admin --admin_password=password --admin_email=wordpress@example.com --skip-email`;
+
+	// -eo pipefail exits the command as soon as anything fails in bash.
+	const setupCommands = [
+		'set -eo pipefail',
+		cliConfigCommand,
+		installCommand,
+	];
+
+	// Bootstrap .htaccess for multisite
+	if ( isMultisite ) {
+		// Using a subshell with `exec` was the best tradeoff I could come up
+		// with between readability of this source and compatibility with the
+		// way that all strings in `setupCommands` are later joined with '&&'.
+		setupCommands.push(
+			`(
+exec > /var/www/html/.htaccess
+echo 'RewriteEngine On'
+echo 'RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]'
+echo 'RewriteBase /'
+echo 'RewriteRule ^index\\.php$ - [L]'
+echo ''
+echo '# add a trailing slash to /wp-admin'
+echo 'RewriteRule ^([_0-9a-zA-Z-]+/)?wp-admin$ $1wp-admin/ [R=301,L]'
+echo ''
+echo 'RewriteCond %{REQUEST_FILENAME} -f [OR]'
+echo 'RewriteCond %{REQUEST_FILENAME} -d'
+echo 'RewriteRule ^ - [L]'
+echo 'RewriteRule ^([_0-9a-zA-Z-]+/)?(wp-(content|admin|includes).*) $2 [L]'
+echo 'RewriteRule ^([_0-9a-zA-Z-]+/)?(.*\\.php)$ $2 [L]'
+echo 'RewriteRule . index.php [L]'
+)`
+		);
+	}
+
+	// WordPress versions below 5.1 didn't use proper spacing in wp-config.
+	const configAnchor =
+		wpVersion && isWPMajorMinorVersionLower( wpVersion, '5.1' )
+			? `"define('WP_DEBUG',"`
+			: `"define( 'WP_DEBUG',"`;
+
+	// Set wp-config.php values.
+	for ( let [ key, value ] of Object.entries(
+		config.env[ environment ].config
+	) ) {
+		// Allow the configuration to skip a default constant by specifying it as null.
+		if ( null === value ) {
+			continue;
+		}
+
+		// Add quotes around string values to work with multi-word strings better.
+		value = typeof value === 'string' ? `"${ value }"` : value;
+		setupCommands.push(
+			`wp config set ${ key } ${ value } --anchor=${ configAnchor }${
+				typeof value !== 'string' ? ' --raw' : ''
+			}`
+		);
+	}
+
+	// Activate all plugins.
+	for ( const pluginSource of config.env[ environment ].pluginSources ) {
+		setupCommands.push( `wp plugin activate ${ pluginSource.basename }` );
+	}
+
+	if ( config.debug ) {
+		spinner.info(
+			`Running the following setup commands on the ${ environment } instance:\n - ${ setupCommands.join(
+				'\n - '
+			) }\n`
+		);
+	}
+
+	// Execute all setup commands in a batch.
+	await dockerCompose.run(
+		environment === 'development' ? 'cli' : 'tests-cli',
+		[ 'bash', '-c', setupCommands.join( ' && ' ) ],
+		{
+			config: config.dockerComposeConfigPath,
+			commandOptions: [ '--rm' ],
+			log: config.debug,
+		}
+	);
+
+	// WordPress versions below 5.1 didn't use proper spacing in wp-config.
+	// Additionally, WordPress versions below 5.4 used `dirname( __FILE__ )` instead of `__DIR__`.
+	let abspathDef = `define( 'ABSPATH', __DIR__ . '\\/' );`;
+	if ( wpVersion && isWPMajorMinorVersionLower( wpVersion, '5.1' ) ) {
+		abspathDef = `define('ABSPATH', dirname(__FILE__) . '\\/');`;
+	} else if ( wpVersion && isWPMajorMinorVersionLower( wpVersion, '5.4' ) ) {
+		abspathDef = `define( 'ABSPATH', dirname( __FILE__ ) . '\\/' );`;
+	}
+
+	// WordPress' PHPUnit suite expects a `wp-tests-config.php` in
+	// the directory that the test suite is contained within.
+	// Make sure ABSPATH points to the WordPress install.
+	await dockerCompose.exec(
+		environment === 'development' ? 'wordpress' : 'tests-wordpress',
+		[
+			'sh',
+			'-c',
+			`sed -e "/^require.*wp-settings.php/d" -e "s/${ abspathDef }/define( 'ABSPATH', '\\/var\\/www\\/html\\/' );\\n\\tdefine( 'WP_DEFAULT_THEME', 'default' );/" /var/www/html/wp-config.php > /wordpress-phpunit/wp-tests-config.php`,
+		],
+		{
+			config: config.dockerComposeConfigPath,
+			log: config.debug,
+		}
+	);
+}
+
+/**
+ * Resets the development server's database, the tests server's database, or both.
+ *
+ * @param {WPEnvironmentSelection} environment The environment to clean. Either 'development', 'tests', or 'all'.
+ * @param {WPConfig}               config      The wp-env config object.
+ */
+async function resetDatabase(
+	environment,
+	{ dockerComposeConfigPath, debug }
+) {
+	const options = {
+		config: dockerComposeConfigPath,
+		commandOptions: [ '--rm' ],
+		log: debug,
+	};
+
+	const tasks = [];
+
+	if ( environment === 'all' || environment === 'development' ) {
+		tasks.push( dockerCompose.run( 'cli', 'wp db reset --yes', options ) );
+	}
+
+	if ( environment === 'all' || environment === 'tests' ) {
+		tasks.push(
+			dockerCompose.run( 'tests-cli', 'wp db reset --yes', options )
+		);
+	}
+
+	await Promise.all( tasks );
+}
+
+/**
+ * Sets up WordPress directories, copying core files if needed.
+ *
+ * @param {WPConfig} config The wp-env config object.
+ */
+async function setupWordPressDirectories( config ) {
+	if (
+		config.env.development.coreSource &&
+		hasSameCoreSource( [ config.env.development, config.env.tests ] )
+	) {
+		await copyCoreFiles(
+			config.env.development.coreSource.path,
+			config.env.development.coreSource.testsPath
+		);
+	}
+}
+
+/**
+ * Returns true if all given environment configs have the same core source.
+ *
+ * @param {WPEnvironmentConfig[]} envs An array of environments to check.
+ *
+ * @return {boolean} True if all the environments have the same core source.
+ */
+function hasSameCoreSource( envs ) {
+	if ( envs.length < 2 ) {
+		return true;
+	}
+	return ! envs.some( ( env ) =>
+		areCoreSourcesDifferent( envs[ 0 ].coreSource, env.coreSource )
+	);
+}
+
+/**
+ * Checks if two core sources are different.
+ *
+ * @param {WPSource} coreSource1 First core source.
+ * @param {WPSource} coreSource2 Second core source.
+ * @return {boolean} True if the sources are different.
+ */
+function areCoreSourcesDifferent( coreSource1, coreSource2 ) {
+	if (
+		( ! coreSource1 && coreSource2 ) ||
+		( coreSource1 && ! coreSource2 )
+	) {
+		return true;
+	}
+
+	if ( coreSource1 && coreSource2 && coreSource1.path !== coreSource2.path ) {
+		return true;
+	}
+
+	return false;
+}
+
+/**
+ * Copies a WordPress installation, taking care to ignore large directories
+ * (.git, node_modules) and configuration files (wp-config.php).
+ *
+ * @param {string} fromPath Path to the WordPress directory to copy.
+ * @param {string} toPath   Destination path.
+ */
+async function copyCoreFiles( fromPath, toPath ) {
+	await copyDir( fromPath, toPath, {
+		filter( stat, filepath, filename ) {
+			if ( stat === 'symbolicLink' ) {
+				return false;
+			}
+			if ( stat === 'directory' && filename === '.git' ) {
+				return false;
+			}
+			if ( stat === 'directory' && filename === 'node_modules' ) {
+				return false;
+			}
+			if ( stat === 'file' && filename === 'wp-config.php' ) {
+				return false;
+			}
+			return true;
+		},
+	} );
+}
+
+module.exports = {
+	configureWordPress,
+	resetDatabase,
+	setupWordPressDirectories,
+	hasSameCoreSource,
+};

package/lib/runtime/errors.js

@@ -0,0 +1,28 @@
+'use strict';
+
+/**
+ * Error thrown when a command is not supported by the current runtime.
+ */
+class UnsupportedCommandError extends Error {
+	constructor( command ) {
+		super(
+			`The '${ command }' command is not supported in the Playground runtime at the moment.`
+		);
+		this.name = 'UnsupportedCommandError';
+	}
+}
+
+/**
+ * Error thrown when the environment has not been initialized.
+ */
+class EnvironmentNotInitializedError extends Error {
+	constructor() {
+		super( 'Environment not initialized. Run `wp-env start` first.' );
+		this.name = 'EnvironmentNotInitializedError';
+	}
+}
+
+module.exports = {
+	UnsupportedCommandError,
+	EnvironmentNotInitializedError,
+};

package/lib/runtime/index.js

@@ -0,0 +1,91 @@
+'use strict';
+
+/**
+ * Internal dependencies
+ */
+const DockerRuntime = require( './docker' );
+const PlaygroundRuntime = require( './playground' );
+const {
+	UnsupportedCommandError,
+	EnvironmentNotInitializedError,
+} = require( './errors' );
+const { setCache, getCache } = require( '../cache' );
+
+const RUNTIME_CACHE_KEY = 'runtime';
+
+const runtimes = {
+	docker: DockerRuntime,
+	playground: PlaygroundRuntime,
+};
+
+/**
+ * Get a runtime instance by name.
+ *
+ * @param {string} name Runtime name ('docker' or 'playground').
+ * @return {Object} Runtime instance.
+ */
+function getRuntime( name ) {
+	const RuntimeClass = runtimes[ name ];
+	if ( ! RuntimeClass ) {
+		throw new Error( `Unknown runtime: ${ name }` );
+	}
+	return new RuntimeClass();
+}
+
+/**
+ * Get all available runtime names.
+ *
+ * @return {string[]} Array of runtime names.
+ */
+function getAvailableRuntimes() {
+	return Object.keys( runtimes );
+}
+
+/**
+ * Save the runtime type to the cache file.
+ * Called when start command initializes the environment.
+ *
+ * @param {string} runtimeName       The runtime name ('docker' or 'playground').
+ * @param {string} workDirectoryPath Path to the wp-env work directory.
+ */
+async function saveRuntime( runtimeName, workDirectoryPath ) {
+	await setCache( RUNTIME_CACHE_KEY, runtimeName, { workDirectoryPath } );
+}
+
+/**
+ * Get the saved runtime type from cache.
+ *
+ * @param {string} workDirectoryPath Path to the wp-env work directory.
+ * @return {Promise<string|undefined>} The saved runtime name, or undefined if not set.
+ */
+async function getSavedRuntime( workDirectoryPath ) {
+	return await getCache( RUNTIME_CACHE_KEY, { workDirectoryPath } );
+}
+
+/**
+ * Detect which runtime was used by reading from the cache.
+ * Throws EnvironmentNotInitializedError if no runtime has been saved.
+ *
+ * @param {string} workDirectoryPath Path to the wp-env work directory.
+ * @return {Promise<string>} Runtime name ('docker' or 'playground').
+ * @throws {EnvironmentNotInitializedError} If environment not initialized.
+ */
+async function detectRuntime( workDirectoryPath ) {
+	const savedRuntime = await getSavedRuntime( workDirectoryPath );
+	if ( ! savedRuntime ) {
+		throw new EnvironmentNotInitializedError();
+	}
+	return savedRuntime;
+}
+
+module.exports = {
+	getRuntime,
+	getAvailableRuntimes,
+	detectRuntime,
+	saveRuntime,
+	getSavedRuntime,
+	DockerRuntime,
+	PlaygroundRuntime,
+	UnsupportedCommandError,
+	EnvironmentNotInitializedError,
+};

package/lib/runtime/playground/blueprint-builder.js

@@ -0,0 +1,158 @@
+'use strict';
+
+/**
+ * Builds a Playground Blueprint from wp-env configuration.
+ *
+ * @param {Object} config The wp-env config object.
+ * @return {Object} Playground Blueprint JSON object.
+ */
+function buildBlueprint( config ) {
+	const envConfig = config.env.development;
+
+	const blueprint = {
+		$schema: 'https://playground.wordpress.net/blueprint-schema.json',
+		landingPage: '/wp-admin/',
+		preferredVersions: {
+			php: envConfig.phpVersion || '8.2',
+			wp: 'latest',
+		},
+		steps: [],
+	};
+
+	// Login step - matches wp-env default credentials
+	blueprint.steps.push( {
+		step: 'login',
+		username: 'admin',
+		password: 'password',
+	} );
+
+	// Add plugins
+	for ( const plugin of envConfig.pluginSources || [] ) {
+		if ( plugin.type === 'local' || plugin.type === 'git' ) {
+			// Local and git plugins are mounted via CLI args, just activate
+			blueprint.steps.push( {
+				step: 'activatePlugin',
+				pluginPath: `/wordpress/wp-content/plugins/${ plugin.basename }`,
+			} );
+		} else if ( plugin.type === 'zip' && plugin.url ) {
+			blueprint.steps.push( {
+				step: 'installPlugin',
+				pluginData: { resource: 'url', url: plugin.url },
+				options: { activate: true },
+			} );
+		} else {
+			throw new Error(
+				`Plugin source "${ plugin.basename || plugin.path }" of type "${
+					plugin.type
+				}" ` +
+					`is not supported with Playground runtime. Only local, git, and zip plugins are supported.`
+			);
+		}
+	}
+
+	// Note: Themes are mounted via CLI args but NOT activated.
+	// This matches Docker runtime behavior where WordPress uses its default theme.
+	// Users can activate themes manually or via wp-cli if needed.
+
+	// Configure wp-config constants
+	const wpConfigConsts = {};
+	for ( const [ key, value ] of Object.entries( envConfig.config || {} ) ) {
+		if ( value !== null ) {
+			wpConfigConsts[ key ] = value;
+		}
+	}
+	if ( Object.keys( wpConfigConsts ).length > 0 ) {
+		blueprint.steps.push( {
+			step: 'defineWpConfigConsts',
+			consts: wpConfigConsts,
+		} );
+	}
+
+	// Handle multisite
+	if ( envConfig.multisite ) {
+		blueprint.steps.push( {
+			step: 'enableMultisite',
+		} );
+	}
+
+	return blueprint;
+}
+
+/**
+ * Get mount arguments for the Playground CLI.
+ *
+ * @param {Object} config The wp-env config object.
+ * @return {string[]} Array of mount arguments.
+ */
+function getMountArgs( config ) {
+	const args = [];
+	const envConfig = config.env.development;
+
+	// Mount plugins
+	for ( const plugin of envConfig.pluginSources || [] ) {
+		if ( plugin.type === 'local' || plugin.type === 'git' ) {
+			args.push(
+				'--mount-dir',
+				plugin.path,
+				`/wordpress/wp-content/plugins/${ plugin.basename }`
+			);
+		} else if ( plugin.type !== 'zip' ) {
+			throw new Error(
+				`Plugin source "${ plugin.basename || plugin.path }" of type "${
+					plugin.type
+				}" ` +
+					`is not supported with Playground runtime. Only local, git, and zip plugins are supported.`
+			);
+		}
+	}
+
+	// Mount themes
+	// All theme types (local, git, zip) can be mounted after downloading/extraction
+	for ( const theme of envConfig.themeSources || [] ) {
+		args.push(
+			'--mount-dir',
+			theme.path,
+			`/wordpress/wp-content/themes/${ theme.basename }`
+		);
+	}
+
+	// Mount custom mappings
+	// All source types (local, git, zip) can be mounted after downloading/extraction
+	for ( const [ wpDir, source ] of Object.entries(
+		envConfig.mappings || {}
+	) ) {
+		args.push( '--mount-dir', source.path, `/wordpress/${ wpDir }` );
+	}
+
+	// Translate core source to Playground's --wp flag or mount it.
+	if ( envConfig.coreSource ) {
+		if ( envConfig.coreSource.type === 'zip' && envConfig.coreSource.url ) {
+			// For zip URLs, let Playground download WordPress natively.
+			args.push( '--wp', envConfig.coreSource.url );
+		} else if ( envConfig.coreSource.type === 'git' ) {
+			// For git sources, pass the version ref to Playground's --wp flag.
+			// e.g., WordPress/WordPress#6.5 → --wp 6.5
+			// WordPress/WordPress (no ref) → default "latest", no flag needed.
+			if ( envConfig.coreSource.ref ) {
+				args.push( '--wp', envConfig.coreSource.ref );
+			}
+		} else {
+			// For local sources, mount the directory and tell Playground to
+			// use the existing files instead of downloading its own copy.
+			args.push(
+				'--mount-dir-before-install',
+				envConfig.coreSource.path,
+				'/wordpress',
+				'--wordpress-install-mode',
+				'install-from-existing-files-if-needed'
+			);
+		}
+	}
+
+	return args;
+}
+
+module.exports = {
+	buildBlueprint,
+	getMountArgs,
+};