@wordpress/env 11.0.1-next.v.0 → 11.0.1-next.v.202602091733.0

package/lib/commands/status.js

@@ -39,15 +39,21 @@ function isEnvironmentInitialized( config ) {
 /**
  * Outputs the status of the wp-env environment.
  *
- * @param {Object}  options
- * @param {Object}  options.spinner A CLI spinner which indicates progress.
- * @param {boolean} options.debug   True if debug mode is enabled.
- * @param {boolean} options.json    True to output as JSON.
+ * @param {Object}      options
+ * @param {Object}      options.spinner A CLI spinner which indicates progress.
+ * @param {boolean}     options.debug   True if debug mode is enabled.
+ * @param {boolean}     options.json    True to output as JSON.
+ * @param {string|null} options.config  Path to a custom .wp-env.json configuration file.
  */
-module.exports = async function status( { spinner, debug, json } ) {
+module.exports = async function status( {
+	spinner,
+	debug,
+	json,
+	config: customConfigPath,
+} ) {
 	spinner.text = 'Getting environment status.';
 
-	const config = await loadConfig( path.resolve( '.' ) );
+	const config = await loadConfig( path.resolve( '.' ), customConfigPath );
 
 	// Check if environment is initialized by looking for runtime-specific files.
 	// We check for these files specifically because the work directory may exist
@@ -70,7 +76,7 @@ module.exports = async function status( { spinner, debug, json } ) {
 	}
 
 	// Detect and get runtime.
-	const runtimeName = detectRuntime( config.workDirectoryPath );
+	const runtimeName = await detectRuntime( config.workDirectoryPath );
 	const runtime = getRuntime( runtimeName );
 
 	// Get status from runtime.

package/lib/commands/stop.js

@@ -13,12 +13,19 @@ const { getRuntime, detectRuntime } = require( '../runtime' );
 /**
  * Stops the development server.
  *
- * @param {Object}  options
- * @param {Object}  options.spinner A CLI spinner which indicates progress.
- * @param {boolean} options.debug   True if debug mode is enabled.
+ * @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|null} options.config  Path to a custom .wp-env.json configuration file.
  */
-module.exports = async function stop( { spinner, debug } ) {
-	const config = await loadConfig( path.resolve( '.' ) );
-	const runtime = getRuntime( detectRuntime( config.workDirectoryPath ) );
+module.exports = async function stop( {
+	spinner,
+	debug,
+	config: customConfigPath,
+} ) {
+	const config = await loadConfig( path.resolve( '.' ), customConfigPath );
+	const runtime = getRuntime(
+		await detectRuntime( config.workDirectoryPath )
+	);
 	await runtime.stop( config, { spinner, debug } );
 };

package/lib/config/get-config-from-environment-vars.js

@@ -23,7 +23,6 @@ const { checkPort, checkVersion, checkString } = require( './validate-config' );
  * @property {?number}                  phpmyadminPort   An override for the development environment's phpMyAdmin port.
  * @property {?WPSource}                coreSource       An override for all environment's coreSource.
  * @property {?string}                  phpVersion       An override for all environment's PHP version.
- * @property {?boolean}                 multisite        An override for if environmen should be multisite.
  * @property {?Object.<string, string>} lifecycleScripts An override for various lifecycle scripts.
  */
 
@@ -69,10 +68,6 @@ module.exports = function getConfigFromEnvironmentVars( cacheDirectoryPath ) {
 		environmentConfig.phpVersion = process.env.WP_ENV_PHP_VERSION;
 	}
 
-	if ( process.env.WP_ENV_MULTISITE ) {
-		environmentConfig.multisite = !! process.env.WP_ENV_MULTISITE;
-	}
-
 	return environmentConfig;
 };
 
@@ -108,6 +103,8 @@ function getLifecycleScriptOverrides() {
 	const lifecycleEnvironmentVars = {
 		WP_ENV_LIFECYCLE_SCRIPT_AFTER_START: 'afterStart',
 		WP_ENV_LIFECYCLE_SCRIPT_AFTER_CLEAN: 'afterClean',
+		WP_ENV_LIFECYCLE_SCRIPT_AFTER_RESET: 'afterReset',
+		WP_ENV_LIFECYCLE_SCRIPT_AFTER_CLEANUP: 'afterCleanup',
 		WP_ENV_LIFECYCLE_SCRIPT_AFTER_DESTROY: 'afterDestroy',
 	};
 	for ( const envVar in lifecycleEnvironmentVars ) {

package/lib/config/load-config.js

@@ -11,6 +11,7 @@ const fs = require( 'fs' ).promises;
 const getCacheDirectory = require( './get-cache-directory' );
 const md5 = require( '../md5' );
 const { parseConfig, getConfigFilePath } = require( './parse-config' );
+const { ValidationError } = require( './validate-config' );
 const postProcessConfig = require( './post-process-config' );
 
 /**
@@ -35,12 +36,31 @@ const postProcessConfig = require( './post-process-config' );
 /**
  * Loads any configuration from a given directory.
  *
- * @param {string} configDirectoryPath The directory we want to load the config from.
+ * @param {string}      configDirectoryPath The directory we want to load the config from.
+ * @param {string|null} customConfigPath    Optional custom config file path.
  *
  * @return {Promise<WPConfig>} The config object we've loaded.
  */
-module.exports = async function loadConfig( configDirectoryPath ) {
-	const configFilePath = getConfigFilePath( configDirectoryPath );
+module.exports = async function loadConfig(
+	configDirectoryPath,
+	customConfigPath = null
+) {
+	const configFilePath = getConfigFilePath(
+		configDirectoryPath,
+		'local',
+		customConfigPath
+	);
+
+	// If a custom config path was provided, verify the file exists.
+	if ( customConfigPath ) {
+		try {
+			await fs.stat( configFilePath );
+		} catch ( error ) {
+			throw new ValidationError(
+				`Config file not found: ${ configFilePath }`
+			);
+		}
+	}
 
 	const cacheDirectoryPath = path.resolve(
 		await getCacheDirectory(),
@@ -49,7 +69,11 @@ module.exports = async function loadConfig( configDirectoryPath ) {
 
 	// Parse any configuration we found in the given directory.
 	// This comes merged and prepared for internal consumption.
-	let config = await parseConfig( configDirectoryPath, cacheDirectoryPath );
+	let config = await parseConfig(
+		configDirectoryPath,
+		cacheDirectoryPath,
+		customConfigPath
+	);
 
 	// Make sure to perform any additional post-processing that
 	// may be needed before the config object is ready for
@@ -64,9 +88,14 @@ module.exports = async function loadConfig( configDirectoryPath ) {
 		),
 		configDirectoryPath,
 		workDirectoryPath: cacheDirectoryPath,
+		customConfigPath,
 		detectedLocalConfig: await hasLocalConfig( [
 			configFilePath,
-			getConfigFilePath( configDirectoryPath, 'override' ),
+			getConfigFilePath(
+				configDirectoryPath,
+				'override',
+				customConfigPath
+			),
 		] ),
 		lifecycleScripts: config.lifecycleScripts,
 		env: config.env,

package/lib/config/parse-config.js

@@ -111,22 +111,27 @@ const DEFAULT_ENVIRONMENT_CONFIG = {
  * constructs an object in the format used internally.
  *
  *
- * @param {string} configDirectoryPath A path to the directory we are parsing the config for.
- * @param {string} cacheDirectoryPath  Path to the work directory located in ~/.wp-env.
+ * @param {string}      configDirectoryPath A path to the directory we are parsing the config for.
+ * @param {string}      cacheDirectoryPath  Path to the work directory located in ~/.wp-env.
+ * @param {string|null} customConfigPath    Optional custom config file path.
  *
  * @return {Promise<WPRootConfig>} Parsed config.
  */
-async function parseConfig( configDirectoryPath, cacheDirectoryPath ) {
+async function parseConfig(
+	configDirectoryPath,
+	cacheDirectoryPath,
+	customConfigPath = null
+) {
 	// The local config will be used to override any defaults.
 	const localConfig = await parseConfigFile(
-		getConfigFilePath( configDirectoryPath ),
+		getConfigFilePath( configDirectoryPath, 'local', customConfigPath ),
 		{ cacheDirectoryPath }
 	);
 
 	// Any overrides that can be used in place
 	// of properties set by the local config.
 	const overrideConfig = await parseConfigFile(
-		getConfigFilePath( configDirectoryPath, 'override' ),
+		getConfigFilePath( configDirectoryPath, 'override', customConfigPath ),
 		{ cacheDirectoryPath }
 	);
 
@@ -161,27 +166,37 @@ async function parseConfig( configDirectoryPath, cacheDirectoryPath ) {
 /**
  * Gets the path to the config file.
  *
- * @param {string} configDirectoryPath The path to the directory containing config files.
- * @param {string} type                The type of config file we're interested in: 'local' or 'override'.
+ * @param {string}      configDirectoryPath The path to the directory containing config files.
+ * @param {string}      type                The type of config file we're interested in: 'local' or 'override'.
+ * @param {string|null} customConfigPath    Optional custom config file path (only used for 'local' type).
  *
  * @return {string} The path to the config file.
  */
-function getConfigFilePath( configDirectoryPath, type = 'local' ) {
-	let fileName;
-	switch ( type ) {
-		case 'local': {
-			fileName = '.wp-env.json';
-			break;
-		}
+function getConfigFilePath(
+	configDirectoryPath,
+	type = 'local',
+	customConfigPath = null
+) {
+	// If a custom config path is provided for the local config, use it.
+	if ( type === 'local' && customConfigPath ) {
+		return path.resolve( customConfigPath );
+	}
 
-		case 'override': {
-			fileName = '.wp-env.override.json';
-			break;
-		}
+	// For override, derive from custom config: staging.json -> staging.override.json
+	if ( type === 'override' && customConfigPath ) {
+		const resolved = path.resolve( customConfigPath );
+		const ext = path.extname( resolved );
+		const base = path.basename( resolved, ext );
+		const dir = path.dirname( resolved );
+		return path.join( dir, `${ base }.override${ ext }` );
+	}
 
-		default: {
-			throw new Error( `Invalid config file type "${ type }.` );
-		}
+	// Default behavior.
+	const fileName =
+		type === 'local' ? '.wp-env.json' : '.wp-env.override.json';
+
+	if ( type !== 'local' && type !== 'override' ) {
+		throw new Error( `Invalid config file type "${ type }.` );
 	}
 
 	return path.resolve( configDirectoryPath, fileName );
@@ -235,6 +250,8 @@ async function getDefaultConfig(
 		lifecycleScripts: {
 			afterStart: null,
 			afterClean: null,
+			afterReset: null,
+			afterCleanup: null,
 			afterDestroy: null,
 		},
 		env: {
@@ -312,6 +329,12 @@ function getEnvironmentVarOverrides( cacheDirectoryPath ) {
 		overrideConfig.env.tests.phpVersion = overrides.phpVersion;
 	}
 
+	if ( overrides.multisite ) {
+		overrideConfig.multisite = overrides.multisite;
+		overrideConfig.env.development.multisite = overrides.multisite;
+		overrideConfig.env.tests.multisite = overrides.multisite;
+	}
+
 	return overrideConfig;
 }
 

package/lib/config/test/__snapshots__/config-integration.js.snap

@@ -3,6 +3,7 @@
 exports[`Config Integration should load local and override configuration files 1`] = `
 {
   "configDirectoryPath": "/test/gutenberg",
+  "customConfigPath": null,
   "detectedLocalConfig": true,
   "dockerComposeConfigPath": "/cache/5fea4c5689ef6cc4a4e6eaaa39323338/docker-compose.yml",
   "env": {
@@ -71,7 +72,9 @@ exports[`Config Integration should load local and override configuration files 1
   },
   "lifecycleScripts": {
     "afterClean": null,
+    "afterCleanup": null,
     "afterDestroy": "test",
+    "afterReset": null,
     "afterStart": null,
   },
   "name": "gutenberg",
@@ -82,6 +85,7 @@ exports[`Config Integration should load local and override configuration files 1
 exports[`Config Integration should load local configuration file 1`] = `
 {
   "configDirectoryPath": "/test/gutenberg",
+  "customConfigPath": null,
   "detectedLocalConfig": true,
   "dockerComposeConfigPath": "/cache/5fea4c5689ef6cc4a4e6eaaa39323338/docker-compose.yml",
   "env": {
@@ -150,7 +154,9 @@ exports[`Config Integration should load local configuration file 1`] = `
   },
   "lifecycleScripts": {
     "afterClean": null,
+    "afterCleanup": null,
     "afterDestroy": null,
+    "afterReset": null,
     "afterStart": "test",
   },
   "name": "gutenberg",
@@ -161,6 +167,7 @@ exports[`Config Integration should load local configuration file 1`] = `
 exports[`Config Integration should use default configuration 1`] = `
 {
   "configDirectoryPath": "/test/gutenberg",
+  "customConfigPath": null,
   "detectedLocalConfig": true,
   "dockerComposeConfigPath": "/cache/5fea4c5689ef6cc4a4e6eaaa39323338/docker-compose.yml",
   "env": {
@@ -229,7 +236,9 @@ exports[`Config Integration should use default configuration 1`] = `
   },
   "lifecycleScripts": {
     "afterClean": null,
+    "afterCleanup": null,
     "afterDestroy": null,
+    "afterReset": null,
     "afterStart": null,
   },
   "name": "gutenberg",
@@ -240,6 +249,7 @@ exports[`Config Integration should use default configuration 1`] = `
 exports[`Config Integration should use environment variables over local and override configuration files 1`] = `
 {
   "configDirectoryPath": "/test/gutenberg",
+  "customConfigPath": null,
   "detectedLocalConfig": true,
   "dockerComposeConfigPath": "/cache/5fea4c5689ef6cc4a4e6eaaa39323338/docker-compose.yml",
   "env": {
@@ -310,7 +320,9 @@ exports[`Config Integration should use environment variables over local and over
   },
   "lifecycleScripts": {
     "afterClean": null,
+    "afterCleanup": null,
     "afterDestroy": null,
+    "afterReset": null,
     "afterStart": "test",
   },
   "name": "gutenberg",

package/lib/config/test/parse-config.js

@@ -52,6 +52,8 @@ const DEFAULT_CONFIG = {
 	lifecycleScripts: {
 		afterStart: null,
 		afterClean: null,
+		afterReset: null,
+		afterCleanup: null,
 		afterDestroy: null,
 	},
 	env: {

package/lib/runtime/docker/build-docker-compose-config.js

@@ -181,6 +181,19 @@ module.exports = function buildDockerComposeConfig( config ) {
 		config.env.tests.phpmyadminPort ?? ''
 	}}:80`;
 
+	// MySQL healthcheck using MariaDB's official healthcheck.sh script.
+	// --connect: verifies TCP connection and that entrypoint has finished
+	// --innodb_initialized: ensures InnoDB storage engine is fully initialized
+	// MARIADB_AUTO_UPGRADE env var ensures healthcheck user exists for existing installations.
+	// Timing is generous to support slow CI environments.
+	const mysqlHealthcheck = {
+		test: [ 'CMD', 'healthcheck.sh', '--connect', '--innodb_initialized' ],
+		interval: '5s',
+		timeout: '10s',
+		retries: 12,
+		start_period: '60s',
+	};
+
 	return {
 		services: {
 			mysql: {
@@ -191,8 +204,11 @@ module.exports = function buildDockerComposeConfig( config ) {
 					MYSQL_ROOT_PASSWORD:
 						dbEnv.credentials.WORDPRESS_DB_PASSWORD,
 					MYSQL_DATABASE: dbEnv.development.WORDPRESS_DB_NAME,
+					// Ensures healthcheck user is created for existing installations.
+					MARIADB_AUTO_UPGRADE: '1',
 				},
 				volumes: [ 'mysql:/var/lib/mysql' ],
+				healthcheck: mysqlHealthcheck,
 			},
 			'tests-mysql': {
 				image: 'mariadb:lts',
@@ -202,11 +218,18 @@ module.exports = function buildDockerComposeConfig( config ) {
 					MYSQL_ROOT_PASSWORD:
 						dbEnv.credentials.WORDPRESS_DB_PASSWORD,
 					MYSQL_DATABASE: dbEnv.tests.WORDPRESS_DB_NAME,
+					// Ensures healthcheck user is created for existing installations.
+					MARIADB_AUTO_UPGRADE: '1',
 				},
 				volumes: [ 'mysql-test:/var/lib/mysql' ],
+				healthcheck: mysqlHealthcheck,
 			},
 			wordpress: {
-				depends_on: [ 'mysql' ],
+				depends_on: {
+					mysql: {
+						condition: 'service_healthy',
+					},
+				},
 				build: {
 					context: '.',
 					dockerfile: 'WordPress.Dockerfile',
@@ -224,7 +247,11 @@ module.exports = function buildDockerComposeConfig( config ) {
 				extra_hosts: [ 'host.docker.internal:host-gateway' ],
 			},
 			'tests-wordpress': {
-				depends_on: [ 'tests-mysql' ],
+				depends_on: {
+					'tests-mysql': {
+						condition: 'service_healthy',
+					},
+				},
 				build: {
 					context: '.',
 					dockerfile: 'Tests-WordPress.Dockerfile',

package/lib/runtime/docker/index.js

@@ -11,7 +11,6 @@ const { rimraf } = require( 'rimraf' );
 /**
  * Promisified dependencies
  */
-const sleep = util.promisify( setTimeout );
 const exec = util.promisify( require( 'child_process' ).exec );
 
 /**
@@ -26,7 +25,6 @@ const {
 	validateRunContainer,
 } = require( './validate-run-container' );
 const {
-	checkDatabaseConnection,
 	configureWordPress,
 	resetDatabase,
 	setupWordPressDirectories,
@@ -109,6 +107,7 @@ class DockerRuntime {
 			xdebug,
 			spx,
 			writeChanges: true,
+			customConfigPath: config.customConfigPath,
 		} );
 
 		// Check if the hash of the config has changed. If so, run configuration.
@@ -174,7 +173,7 @@ class DockerRuntime {
 		}
 
 		await Promise.all( [
-			dockerCompose.upOne( 'mysql', {
+			dockerCompose.upMany( [ 'mysql', 'tests-mysql' ], {
 				...dockerComposeConfig,
 				commandOptions: shouldConfigureWp
 					? [ '--build', '--force-recreate' ]
@@ -250,19 +249,6 @@ class DockerRuntime {
 		if ( shouldConfigureWp ) {
 			spinner.text = 'Configuring WordPress.';
 
-			try {
-				await checkDatabaseConnection( fullConfig );
-			} catch ( error ) {
-				// Wait 30 seconds for MySQL to accept connections.
-				await retry( () => checkDatabaseConnection( fullConfig ), {
-					times: 30,
-					delay: 1000,
-				} );
-
-				// It takes 3-4 seconds for MySQL to be ready after it starts accepting connections.
-				await sleep( 4000 );
-			}
-
 			// Retry WordPress installation in case MySQL *still* wasn't ready.
 			await Promise.all( [
 				retry(
@@ -369,6 +355,15 @@ class DockerRuntime {
 		return 'WARNING! This will remove Docker containers, volumes, networks, and images associated with the WordPress instance.';
 	}
 
+	/**
+	 * Get the warning message for cleanup confirmation.
+	 *
+	 * @return {string} Warning message.
+	 */
+	getCleanupWarningMessage() {
+		return 'WARNING! This will remove Docker containers, volumes, networks, and local files associated with the WordPress instance. Docker images will be preserved.';
+	}
+
 	/**
 	 * Stop the Docker containers.
 	 *
@@ -381,6 +376,7 @@ class DockerRuntime {
 		const { dockerComposeConfigPath } = await initConfig( {
 			spinner,
 			debug,
+			customConfigPath: config.customConfigPath,
 		} );
 
 		spinner.text = 'Stopping WordPress.';
@@ -413,7 +409,8 @@ class DockerRuntime {
 		spinner.text = 'Removing local files.';
 		// Note: there is a race condition where docker compose actually hasn't finished
 		// by this point, which causes rimraf to fail. We need to wait at least 2.5-5s,
-		// but using 10s in case it's dependant on the machine.
+		// but using 10s in case it's dependent on the machine. Removing images takes
+		// longer so we use a longer wait time here.
 		await new Promise( ( resolve ) => setTimeout( resolve, 10000 ) );
 		await rimraf( config.workDirectoryPath );
 
@@ -421,27 +418,68 @@ class DockerRuntime {
 	}
 
 	/**
-	 * Clean/reset the WordPress database.
+	 * Cleanup the Docker containers and remove local files, but preserve images.
+	 *
+	 * @param {WPConfig} config          The wp-env config object.
+	 * @param {Object}   options         Cleanup options.
+	 * @param {Object}   options.spinner A CLI spinner which indicates progress.
+	 * @param {boolean}  options.debug   True if debug mode is enabled.
+	 */
+	async cleanup( config, { spinner, debug } ) {
+		spinner.text = 'Removing docker containers, volumes, and networks.';
+
+		await dockerCompose.down( {
+			config: config.dockerComposeConfigPath,
+			commandOptions: [ '--volumes', '--remove-orphans' ],
+			log: debug,
+		} );
+
+		spinner.text = 'Removing local files.';
+		// Note: there is a race condition where docker compose actually hasn't finished
+		// by this point, which causes rimraf to fail. We need to wait at least 2.5-5s,
+		// but since we're not removing images, the wait can be shorter.
+		await new Promise( ( resolve ) => setTimeout( resolve, 3000 ) );
+		await rimraf( config.workDirectoryPath );
+
+		spinner.text = 'Cleaned up WordPress environment.';
+	}
+
+	/**
+	 * Reset the WordPress database.
 	 *
 	 * @param {WPConfig} config              The wp-env config object.
-	 * @param {Object}   options             Clean options.
-	 * @param {string}   options.environment The environment to clean.
+	 * @param {Object}   options             Reset options.
+	 * @param {string}   options.environment The environment to reset.
 	 * @param {Object}   options.spinner     A CLI spinner which indicates progress.
 	 * @param {boolean}  options.debug       True if debug mode is enabled.
 	 */
 	async clean( config, { environment, spinner, debug } ) {
-		const fullConfig = await initConfig( { spinner, debug } );
+		const fullConfig = await initConfig( {
+			spinner,
+			debug,
+			customConfigPath: config.customConfigPath,
+		} );
 
 		const description = `${ environment } environment${
 			environment === 'all' ? 's' : ''
 		}`;
-		spinner.text = `Cleaning ${ description }.`;
+		spinner.text = `Resetting ${ description }.`;
 
 		const tasks = [];
 
-		// Start the database first to avoid race conditions where all tasks create
-		// different docker networks with the same name.
-		await dockerCompose.upOne( 'mysql', {
+		// Start the appropriate MySQL service(s) first to avoid race conditions
+		// where parallel tasks try to create docker networks with the same name.
+		// The dependency chain (cli -> wordpress -> mysql with service_healthy)
+		// ensures MySQL is ready before database operations run.
+		const mysqlServices = [];
+		if ( environment === 'all' || environment === 'development' ) {
+			mysqlServices.push( 'mysql' );
+		}
+		if ( environment === 'all' || environment === 'tests' ) {
+			mysqlServices.push( 'tests-mysql' );
+		}
+
+		await dockerCompose.upMany( mysqlServices, {
 			config: fullConfig.dockerComposeConfigPath,
 			log: fullConfig.debug,
 		} );
@@ -466,7 +504,7 @@ class DockerRuntime {
 
 		await Promise.all( tasks );
 
-		spinner.text = `Cleaned ${ description }.`;
+		spinner.text = `Reset ${ description }.`;
 	}
 
 	/**
@@ -493,7 +531,11 @@ class DockerRuntime {
 		// Validate the container name (throws for deprecated containers)
 		validateRunContainer( container );
 
-		const fullConfig = await initConfig( { spinner, debug } );
+		const fullConfig = await initConfig( {
+			spinner,
+			debug,
+			customConfigPath: config.customConfigPath,
+		} );
 
 		// Shows a contextual tip for the given command.
 		const joinedCommand = command.join( ' ' );
@@ -520,7 +562,11 @@ class DockerRuntime {
 	 * @param {boolean}  options.debug       True if debug mode is enabled.
 	 */
 	async logs( config, { environment, watch, spinner, debug } ) {
-		const fullConfig = await initConfig( { spinner, debug } );
+		const fullConfig = await initConfig( {
+			spinner,
+			debug,
+			customConfigPath: config.customConfigPath,
+		} );
 
 		// If we show text while watching the logs, it will continue showing up every
 		// few lines in the logs as they happen, which isn't a good look. So only
@@ -589,7 +635,11 @@ class DockerRuntime {
 	async getStatus( config, { spinner, debug } ) {
 		spinner.text = 'Getting environment status.';
 
-		const fullConfig = await initConfig( { spinner, debug } );
+		const fullConfig = await initConfig( {
+			spinner,
+			debug,
+			customConfigPath: config.customConfigPath,
+		} );
 		const dockerComposeConfig = {
 			config: fullConfig.dockerComposeConfigPath,
 			log: debug,

package/lib/runtime/docker/init-config.js

@@ -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