@wordpress/env 7.0.0 → 8.0.0

package/README.md

@@ -319,40 +319,38 @@ Options:
   --scripts  Execute any configured lifecycle scripts. [boolean] [default: true]
 ```
 
-### `wp-env run [container] [command]`
+### `wp-env run <container> [command...]`
 
-The run command can be used to open shell sessions or invoke WP-CLI commands.
+The run command can be used to open shell sessions, invoke WP-CLI commands, or run any arbitrary commands inside of a container.
 
-<div class="callout callout-alert">In some cases, <code>wp-env</code> may consume options that you are attempting to pass to
-the container. This happens with options that <code>wp-env</code> has already declared,
-such as <code>--env-cwd</code>, <code>--debug</code>, <code>--help</code>, and <code>--version</code>. When this happens, you should fall
-back to using quotation marks; <code>wp-env</code> considers everything inside the
-quotation marks to be command argument.
-
-For example, to ask <code>WP-CLI</code> for its help text:
-
-<pre>sh
-<code class="language-sh">wp-env run cli "wp --help"</code></pre>
-
-Without the quotation marks, <code>wp-env</code> will print its own help text instead of
-passing it to the container. If you experience any problems where the command
-is not being passed correctly, fall back to using quotation marks.
+<div class="callout callout-alert">
+<p>
+In some cases <code class="language-sh">wp-env run</code> may conflict with options that you are passing to the container.
+When this happens, <code class="language-sh">wp-env</code> will treat the option as its own and take action accordingly.
+For example, if you try <code class="language-sh">wp-env run cli php --help</code>, you will receive the <code class="language-sh">wp-env</code> help text.
+</p>
 
+<p>
+You can get around this by passing any conflicting options after a double dash. <code class="language-sh">wp-env</code> will not process anything after
+the double dash and will simply pass it on to the container. To get the PHP help text you would use <code class="language-sh">wp-env run cli php -- --help</code>.
+</p>
 </div>
 
 ```sh
-wp-env run <container> [command..]
+wp-env run <container> [command...]
 
-Runs an arbitrary command in one of the underlying Docker containers. The
-"container" param should reference one of the underlying Docker services like
-"development", "tests", or "cli". To run a wp-cli command, use the "cli" or
-"tests-cli" service. You can also use this command to open shell sessions like
-bash and the WordPress shell in the WordPress instance. For example, `wp-env run
-cli bash` will open bash in the development WordPress instance.
+Runs an arbitrary command in one of the underlying Docker containers. A double
+dash can be used to pass arguments to the container without parsing them. This
+is necessary if you are using an option that is defined below. You can use
+`bash` to open a shell session and both `composer` and `phpunit` are available
+in all WordPress and CLI containers. WP-CLI is also available in the CLI
+containers.
 
 Positionals:
-  container  The container to run the command on.            [string] [required]
-  command    The command to run.                           [array] [default: []]
+  container  The Docker service to run the command on.
+              [string] [required] [choices: "mysql", "tests-mysql", "wordpress",
+                   "tests-wordpress", "cli", "tests-cli", "composer", "phpunit"]
+  command    The command to run.                                      [required]
 
 Options:
   --debug    Enable debug output.                     [boolean] [default: false]
@@ -443,7 +441,8 @@ Destroy the WordPress environment. Deletes docker containers, volumes, and
 networks associated with the WordPress environment and removes local files.
 
 Options:
-  --debug            Enable debug output.             [boolean] [default: false]
+  --debug    Enable debug output.                     [boolean] [default: false]
+  --scripts  Execute any configured lifecycle scripts. [boolean] [default: true]
 ```
 
 ### `wp-env logs [environment]`
@@ -559,19 +558,16 @@ These can be overridden by setting a value within the `config` configuration. Se
 
 Additionally, the values referencing a URL include the specified port for the given environment. So if you set `testsPort: 3000, port: 2000`, `WP_HOME` (for example) will be `http://localhost:3000` on the tests instance and `http://localhost:2000` on the development instance.
 
-## Lifecycle Hooks
-
-These hooks are executed at certain points during the lifecycle of a command's execution. Keep in mind that these will be executed on both fresh and existing
-environments, so, ensure any commands you build won't break on subsequent executions.
-
-### After Setup
+## Lifecycle Scripts
 
-Using the `afterSetup` option in `.wp-env.json` files will allow you to configure an arbitrary command to execute after the environment's setup is complete:
+Using the `lifecycleScripts` option in `.wp-env.json` will allow you to set arbitrary commands to be executed at certain points in the lifecycle. This configuration
+can also be overridden using `WP_ENV_LIFECYCLE_SCRIPT_{LIFECYCLE_EVENT}` environment variables, with the remainder being the all-caps snake_case name of the option, for
+example, `WP_ENV_LIFECYCLE_SCRIPT_AFTER_START`. Keep in mind that these will be executed on both fresh and existing environments, so, ensure any commands you
+build won't break on subsequent executions.
 
--   `wp-env start`: Runs when the config changes, WordPress updates, or you pass the `--update` flag.
--   `wp-env clean`: Runs after the selected environments have been cleaned.
-
-You can override the `afterSetup` option using the `WP_ENV_AFTER_SETUP` environment variable.
+* `afterStart`: Runs after `wp-env start` has finished setting up the environment.
+* `afterClean`: Runs after `wp-env clean` has finished cleaning the environment.
+* `afterDestroy`: Runs after `wp-env destroy` has destroyed the environment.
 
 ## Examples
 
@@ -707,7 +703,9 @@ This is useful for performing some actions after setting up the environment, suc
 
 ```json
 {
-	"afterSetup": "node tests/e2e/bin/setup-env.js"
+	"lifecycleScripts": {
+		"afterStart": "node tests/e2e/bin/setup-env.js"
+	}
 }
 ```
 

package/lib/cli.js

@@ -13,6 +13,10 @@ const { execSync } = require( 'child_process' );
  */
 const env = require( './env' );
 const parseXdebugMode = require( './parse-xdebug-mode' );
+const {
+	RUN_CONTAINERS,
+	validateRunContainer,
+} = require( './validate-run-container' );
 
 // Colors.
 const boldWhite = chalk.bold.white;
@@ -41,7 +45,7 @@ const withSpinner =
 			( error ) => {
 				if (
 					error instanceof env.ValidationError ||
-					error instanceof env.AfterSetupError
+					error instanceof env.LifecycleScriptError
 				) {
 					// Error is a configuration error. That means the user did something wrong.
 					spinner.fail( error.message );
@@ -99,9 +103,12 @@ module.exports = function cli() {
 		default: false,
 	} );
 
-	// Make sure any unknown arguments are passed to the command as arguments.
-	// This allows options to be passed to "run" without being quoted.
-	yargs.parserConfiguration( { 'unknown-options-as-args': true } );
+	yargs.parserConfiguration( {
+		// Treats unknown options as arguments for commands to deal with instead of discarding them.
+		'unknown-options-as-args': true,
+		// Populates '--' in the command options with arguments after the double dash.
+		'populate--': true,
+	} );
 
 	yargs.command(
 		'start',
@@ -184,8 +191,8 @@ module.exports = function cli() {
 		'Displays the latest logs for the e2e test environment without watching.'
 	);
 	yargs.command(
-		'run <container> [command..]',
-		'Runs an arbitrary command in one of the underlying Docker containers. The "container" param should reference one of the underlying Docker services like "development", "tests", or "cli". To run a wp-cli command, use the "cli" or "tests-cli" service. You can also use this command to open shell sessions like bash and the WordPress shell in the WordPress instance. For example, `wp-env run cli bash` will open bash in the development WordPress instance. When using long commands with arguments and quotation marks, you need to wrap the "command" param in quotation marks. For example: `wp-env run tests-cli "wp post create --post_type=page --post_title=\'Test\'"` will create a post on the tests WordPress instance.',
+		'run <container> [command...]',
+		'Runs an arbitrary command in one of the underlying Docker containers. A double dash can be used to pass arguments to the container without parsing them. This is necessary if you are using an option that is defined below. You can use `bash` to open a shell session and both `composer` and `phpunit` are available in all WordPress and CLI containers. WP-CLI is also available in the CLI containers.',
 		( args ) => {
 			args.option( 'env-cwd', {
 				type: 'string',
@@ -196,7 +203,10 @@ module.exports = function cli() {
 			} );
 			args.positional( 'container', {
 				type: 'string',
-				describe: 'The container to run the command on.',
+				describe:
+					'The underlying Docker service to run the command on.',
+				choices: RUN_CONTAINERS,
+				coerce: validateRunContainer,
 			} );
 			args.positional( 'command', {
 				type: 'array',
@@ -223,7 +233,13 @@ module.exports = function cli() {
 		wpRed(
 			'Destroy the WordPress environment. Deletes docker containers, volumes, and networks associated with the WordPress environment and removes local files.'
 		),
-		() => {},
+		( args ) => {
+			args.option( 'scripts', {
+				type: 'boolean',
+				describe: 'Execute any configured lifecycle scripts.',
+				default: true,
+			} );
+		},
 		withSpinner( env.destroy )
 	);
 	yargs.command(

package/lib/commands/clean.js

@@ -9,7 +9,7 @@ const dockerCompose = require( 'docker-compose' );
  */
 const initConfig = require( '../init-config' );
 const { configureWordPress, resetDatabase } = require( '../wordpress' );
-const { executeAfterSetup } = require( '../execute-after-setup' );
+const { executeLifecycleScript } = require( '../execute-lifecycle-script' );
 
 /**
  * @typedef {import('../wordpress').WPEnvironment} WPEnvironment
@@ -65,9 +65,8 @@ module.exports = async function clean( {
 
 	await Promise.all( tasks );
 
-	// Execute any configured command that should run after the environment has finished being set up.
 	if ( scripts ) {
-		executeAfterSetup( config, spinner );
+		await executeLifecycleScript( 'afterClean', config, spinner );
 	}
 
 	spinner.text = `Cleaned ${ description }.`;

package/lib/commands/destroy.js

@@ -17,21 +17,21 @@ const rimraf = util.promisify( require( 'rimraf' ) );
  * Internal dependencies
  */
 const { loadConfig } = require( '../config' );
+const { executeLifecycleScript } = require( '../execute-lifecycle-script' );
 
 /**
  * Destroy the development server.
  *
  * @param {Object}  options
  * @param {Object}  options.spinner A CLI spinner which indicates progress.
+ * @param {boolean} options.scripts Indicates whether or not lifecycle scripts should be executed.
  * @param {boolean} options.debug   True if debug mode is enabled.
  */
-module.exports = async function destroy( { spinner, debug } ) {
-	const { dockerComposeConfigPath, workDirectoryPath } = await loadConfig(
-		path.resolve( '.' )
-	);
+module.exports = async function destroy( { spinner, scripts, debug } ) {
+	const config = await loadConfig( path.resolve( '.' ) );
 
 	try {
-		await fs.readdir( workDirectoryPath );
+		await fs.readdir( config.workDirectoryPath );
 	} catch {
 		spinner.text = 'Could not find any files to remove.';
 		return;
@@ -60,7 +60,7 @@ module.exports = async function destroy( { spinner, debug } ) {
 	spinner.text = 'Removing docker images, volumes, and networks.';
 
 	await dockerCompose.down( {
-		config: dockerComposeConfigPath,
+		config: config.dockerComposeConfigPath,
 		commandOptions: [ '--volumes', '--remove-orphans', '--rmi', 'all' ],
 		log: debug,
 	} );
@@ -70,7 +70,11 @@ module.exports = async function destroy( { spinner, debug } ) {
 	// 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.
 	await new Promise( ( resolve ) => setTimeout( resolve, 10000 ) );
-	await rimraf( workDirectoryPath );
+	await rimraf( config.workDirectoryPath );
+
+	if ( scripts ) {
+		await executeLifecycleScript( 'afterDestroy', config, spinner );
+	}
 
 	spinner.text = 'Removed WordPress environment.';
 };

package/lib/commands/run.js

@@ -10,7 +10,6 @@ const path = require( 'path' );
  */
 const initConfig = require( '../init-config' );
 const getHostUser = require( '../get-host-user' );
-const { ValidationError } = require( '../config' );
 
 /**
  * @typedef {import('../config').WPConfig} WPConfig
@@ -22,6 +21,7 @@ const { ValidationError } = require( '../config' );
  * @param {Object}   options
  * @param {string}   options.container The Docker container to run the command on.
  * @param {string[]} options.command   The command to run.
+ * @param {string[]} options.'--'      Any arguments that were passed after a double dash.
  * @param {string}   options.envCwd    The working directory for the command to be executed from.
  * @param {Object}   options.spinner   A CLI spinner which indicates progress.
  * @param {boolean}  options.debug     True if debug mode is enabled.
@@ -29,66 +29,34 @@ const { ValidationError } = require( '../config' );
 module.exports = async function run( {
 	container,
 	command,
+	'--': doubleDashedArgs,
 	envCwd,
 	spinner,
 	debug,
 } ) {
-	validateContainerExistence( container );
-
 	const config = await initConfig( { spinner, debug } );
 
-	command = command.join( ' ' );
+	// Include any double dashed arguments in the command so that we can pass them to Docker.
+	// This lets users pass options that the command defines without them being parsed.
+	if ( Array.isArray( doubleDashedArgs ) ) {
+		command.push( ...doubleDashedArgs );
+	}
 
 	// Shows a contextual tip for the given command.
-	showCommandTips( command, container, spinner );
+	const joinedCommand = command.join( ' ' );
+	showCommandTips( joinedCommand, container, spinner );
 
 	await spawnCommandDirectly( config, container, command, envCwd, spinner );
 
-	spinner.text = `Ran \`${ command }\` in '${ container }'.`;
+	spinner.text = `Ran \`${ joinedCommand }\` in '${ container }'.`;
 };
 
-/**
- * Validates the container option and throws if it is invalid.
- *
- * @param {string} container The Docker container to run the command on.
- */
-function validateContainerExistence( container ) {
-	// Give better errors for containers that we have removed.
-	if ( container === 'phpunit' ) {
-		throw new ValidationError(
-			"The 'phpunit' container has been removed. Please use 'wp-env run tests-cli --env-cwd=wp-content/path/to/plugin phpunit' instead."
-		);
-	}
-	if ( container === 'composer' ) {
-		throw new ValidationError(
-			"The 'composer' container has been removed. Please use 'wp-env run cli --env-cwd=wp-content/path/to/plugin composer' instead."
-		);
-	}
-
-	// Provide better error output than Docker's "service does not exist" messaging.
-	const validContainers = [
-		'mysql',
-		'tests-mysql',
-		'wordpress',
-		'tests-wordpress',
-		'cli',
-		'tests-cli',
-	];
-	if ( ! validContainers.includes( container ) ) {
-		throw new ValidationError(
-			`The '${ container }' container does not exist. Valid selections are: ${ validContainers.join(
-				', '
-			) }`
-		);
-	}
-}
-
 /**
  * Runs an arbitrary command on the given Docker container.
  *
  * @param {WPConfig} config    The wp-env configuration.
  * @param {string}   container The Docker container to run the command on.
- * @param {string}   command   The command to run.
+ * @param {string[]} command   The command to run.
  * @param {string}   envCwd    The working directory for the command to be executed from.
  * @param {Object}   spinner   A CLI spinner which indicates progress.
  */
@@ -99,8 +67,9 @@ function spawnCommandDirectly( config, container, command, envCwd, spinner ) {
 	// to interact with the files mounted from the host.
 	const hostUser = getHostUser();
 
-	// We need to pass absolute paths to the container.
-	envCwd = path.resolve(
+	// Since Docker requires absolute paths, we should resolve the input to a POSIX path.
+	// This is needed because Windows resolves relative paths from the C: drive.
+	envCwd = path.posix.resolve(
 		// Not all containers have the same starting working directory.
 		container === 'mysql' || container === 'tests-mysql'
 			? '/'
@@ -108,20 +77,22 @@ function spawnCommandDirectly( config, container, command, envCwd, spinner ) {
 		envCwd
 	);
 
-	const isTTY = process.stdout.isTTY;
 	const composeCommand = [
 		'-f',
 		config.dockerComposeConfigPath,
 		'exec',
-		! isTTY ? '-T' : '',
 		'-w',
 		envCwd,
 		'--user',
 		hostUser.fullUser,
-		container,
-		...command.split( ' ' ), // The command will fail if passed as a complete string.
 	];
 
+	if ( ! process.stdout.isTTY ) {
+		composeCommand.push( '-T' );
+	}
+
+	composeCommand.push( container, ...command );
+
 	return new Promise( ( resolve, reject ) => {
 		// Note: since the npm docker-compose package uses the -T option, we
 		// cannot use it to spawn an interactive command. Thus, we run docker-
@@ -129,10 +100,7 @@ function spawnCommandDirectly( config, container, command, envCwd, spinner ) {
 		const childProc = spawn(
 			'docker-compose',
 			composeCommand,
-			{
-				stdio: 'inherit',
-				shell: true,
-			},
+			{ stdio: 'inherit' },
 			spinner
 		);
 		childProc.on( 'error', reject );
@@ -153,17 +121,17 @@ function spawnCommandDirectly( config, container, command, envCwd, spinner ) {
  * bash) may have weird behavior (exit with ctrl-d instead of ctrl-c or ctrl-z),
  * so we want the user to have that information without having to ask someone.
  *
- * @param {string} command   The command for which to show a tip.
- * @param {string} container The container the command will be run on.
- * @param {Object} spinner   A spinner object to show progress.
+ * @param {string} joinedCommand The command for which to show a tip joined by spaces.
+ * @param {string} container     The container the command will be run on.
+ * @param {Object} spinner       A spinner object to show progress.
  */
-function showCommandTips( command, container, spinner ) {
-	if ( ! command.length ) {
+function showCommandTips( joinedCommand, container, spinner ) {
+	if ( ! joinedCommand.length ) {
 		return;
 	}
 
-	const tip = `Starting '${ command }' on the ${ container } container. ${ ( () => {
-		switch ( command ) {
+	const tip = `Starting '${ joinedCommand }' on the ${ container } container. ${ ( () => {
+		switch ( joinedCommand ) {
 			case 'bash':
 				return 'Exit bash with ctrl-d.';
 			case 'wp shell':

package/lib/commands/start.js

@@ -31,7 +31,7 @@ const {
 } = require( '../wordpress' );
 const { didCacheChange, setCache } = require( '../cache' );
 const md5 = require( '../md5' );
-const { executeAfterSetup } = require( '../execute-after-setup' );
+const { executeLifecycleScript } = require( '../execute-lifecycle-script' );
 
 /**
  * @typedef {import('../config').WPConfig} WPConfig
@@ -203,17 +203,16 @@ module.exports = async function start( {
 			} ),
 		] );
 
-		// Execute any configured command that should run after the environment has finished being set up.
-		if ( scripts ) {
-			executeAfterSetup( config, spinner );
-		}
-
 		// Set the cache key once everything has been configured.
 		await setCache( CONFIG_CACHE_KEY, configHash, {
 			workDirectoryPath,
 		} );
 	}
 
+	if ( scripts ) {
+		await executeLifecycleScript( 'afterStart', config, spinner );
+	}
+
 	const siteUrl = config.env.development.config.WP_SITEURL;
 	const testsSiteUrl = config.env.tests.config.WP_SITEURL;
 

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

@@ -16,10 +16,11 @@ const { checkPort, checkVersion, checkString } = require( './validate-config' );
  * Environment variable configuration.
  *
  * @typedef WPEnvironmentVariableConfig
- * @property {?number}   port       An override for the development environment's port.
- * @property {?number}   testsPort  An override for the testing environment's port.
- * @property {?WPSource} coreSource An override for all environment's coreSource.
- * @property {?string}   phpVersion An override for all environment's PHP version.
+ * @property {?number}                  port             An override for the development environment's port.
+ * @property {?number}                  testsPort        An override for the testing environment's port.
+ * @property {?WPSource}                coreSource       An override for all environment's coreSource.
+ * @property {?string}                  phpVersion       An override for all environment's PHP version.
+ * @property {?Object.<string, string>} lifecycleScripts An override for various lifecycle scripts.
  */
 
 /**
@@ -33,6 +34,7 @@ module.exports = function getConfigFromEnvironmentVars( cacheDirectoryPath ) {
 	const environmentConfig = {
 		port: getPortFromEnvironmentVariable( 'WP_ENV_PORT' ),
 		testsPort: getPortFromEnvironmentVariable( 'WP_ENV_TESTS_PORT' ),
+		lifecycleScripts: getLifecycleScriptOverrides(),
 	};
 
 	if ( process.env.WP_ENV_CORE ) {
@@ -53,15 +55,6 @@ module.exports = function getConfigFromEnvironmentVars( cacheDirectoryPath ) {
 		environmentConfig.phpVersion = process.env.WP_ENV_PHP_VERSION;
 	}
 
-	if ( process.env.WP_ENV_AFTER_SETUP ) {
-		checkString(
-			'environment variable',
-			'WP_ENV_AFTER_SETUP',
-			process.env.WP_ENV_AFTER_SETUP
-		);
-		environmentConfig.afterSetup = process.env.WP_ENV_AFTER_SETUP;
-	}
-
 	return environmentConfig;
 };
 
@@ -70,7 +63,7 @@ module.exports = function getConfigFromEnvironmentVars( cacheDirectoryPath ) {
  *
  * @param {string} varName The environment variable to check (e.g. WP_ENV_PORT).
  *
- * @return {number} The parsed port number
+ * @return {number} The parsed port number.
  */
 function getPortFromEnvironmentVariable( varName ) {
 	if ( ! process.env[ varName ] ) {
@@ -84,3 +77,30 @@ function getPortFromEnvironmentVariable( varName ) {
 
 	return port;
 }
+
+/**
+ * Parses the lifecycle script environment variables.
+ *
+ * @return {Object.<string, string>} The parsed lifecycle scripts.
+ */
+function getLifecycleScriptOverrides() {
+	const lifecycleScripts = {};
+
+	// Find all of the lifecycle script overrides and parse them.
+	const lifecycleEnvironmentVars = {
+		WP_ENV_LIFECYCLE_SCRIPT_AFTER_START: 'afterStart',
+		WP_ENV_LIFECYCLE_SCRIPT_AFTER_CLEAN: 'afterClean',
+		WP_ENV_LIFECYCLE_SCRIPT_AFTER_DESTROY: 'afterDestroy',
+	};
+	for ( const envVar in lifecycleEnvironmentVars ) {
+		const scriptValue = process.env[ envVar ];
+		if ( scriptValue === undefined ) {
+			continue;
+		}
+
+		checkString( 'environment variable', envVar, scriptValue );
+		lifecycleScripts[ lifecycleEnvironmentVars[ envVar ] ] = scriptValue;
+	}
+
+	return lifecycleScripts;
+}

package/lib/config/load-config.js

@@ -27,7 +27,7 @@ const postProcessConfig = require( './post-process-config' );
  * @property {string}                               workDirectoryPath       Path to the work directory located in ~/.wp-env.
  * @property {string}                               dockerComposeConfigPath Path to the docker-compose.yml file.
  * @property {boolean}                              detectedLocalConfig     If true, wp-env detected local config and used it.
- * @property {string}                               afterSetup              The command(s) to run after configuring WordPress on start and clean.
+ * @property {Object.<string, string>}              lifecycleScripts        Any lifecycle scripts that we might need to execute.
  * @property {Object.<string, WPEnvironmentConfig>} env                     Specific config for different environments.
  * @property {boolean}                              debug                   True if debug mode is enabled.
  */
@@ -68,7 +68,7 @@ module.exports = async function loadConfig( configDirectoryPath ) {
 			configFilePath,
 			getConfigFilePath( configDirectoryPath, 'override' ),
 		] ),
-		afterSetup: config.afterSetup,
+		lifecycleScripts: config.lifecycleScripts,
 		env: config.env,
 	};
 };

package/lib/config/merge-configs.js

@@ -45,7 +45,8 @@ function mergeConfig( config, toMerge ) {
 		switch ( option ) {
 			// Some config options are merged together instead of entirely replaced.
 			case 'config':
-			case 'mappings': {
+			case 'mappings':
+			case 'lifecycleScripts': {
 				config[ option ] = Object.assign(
 					config[ option ],
 					toMerge[ option ]