@wordpress/env 6.0.0 → 7.0.0

package/README.md

@@ -175,32 +175,33 @@ $ wp-env destroy
 $ wp-env start
 ```
 
-### 7. Debug mode and inspecting the generated dockerfile.
+## Using included WordPress PHPUnit test files
 
-`wp-env` uses docker behind the scenes. Inspecting the generated docker-compose file can help to understand what's going on.
+Out of the box `wp-env` includes the [WordPress' PHPUnit test files](https://develop.svn.wordpress.org/trunk/tests/phpunit/) corresponding to the version of WordPress installed. There is an environment variable, `WP_TESTS_DIR`, which points to the location of these files within each container. By including these files in the environment, we remove the need for you to use a package or install and mount them yourself. If you do not want to use these files, you should ignore the `WP_TESTS_DIR` environment variable and load them from the location of your choosing.
 
-Start `wp-env` in debug mode
+### Customizing the `wp-tests-config.php` file
 
-```sh
-wp-env start --debug
-```
+While we do provide a default `wp-tests-config.php` file within the environment, there may be cases where you want to use your own. WordPress provides a `WP_TESTS_CONFIG_FILE_PATH` constant that you can use to change the `wp-config.php` file used for testing. Set this to a desired path in your `bootstrap.php` file and the file you've chosen will be used instead of the one included in the environment.
 
-`wp-env` will output its config which includes `dockerComposeConfigPath`.
+## Using `composer`, `phpunit`, and `wp-cli` tools.
 
-```sh
-ℹ Config:
-	...
-	"dockerComposeConfigPath": "/Users/$USERNAME/.wp-env/5a619d332a92377cd89feb339c67b833/docker-compose.yml",
-	...
-```
+For ease of use, Composer, PHPUnit, and wp-cli are available for in the environment. To run these executables, use `wp-env run <env> <tool> <command>`. For example, `wp-env run cli composer install`, or `wp-env run tests-cli phpunit`. You can also access various shells like `wp-env run cli bash` or `wp-env run cli wp shell`.
 
-## Using included WordPress PHPUnit test files
+For the `env` part, `cli` and `wordpress` share a database and mapped volumes, but more tools are available in the cli environment. You should use the `tests-cli` / `tests-wordpress` environments for a separate testing database.
 
-Out of the box `wp-env` includes the [WordPress' PHPUnit test files](https://develop.svn.wordpress.org/trunk/tests/phpunit/) corresponding to the version of WordPress installed. There is an environment variable, `WP_TESTS_DIR`, which points to the location of these files within each container. By including these files in the environment, we remove the need for you to use a package or install and mount them yourself. If you do not want to use these files, you should ignore the `WP_TESTS_DIR` environment variable and load them from the location of your choosing.
+By default, the cwd of the run command is the root of the WordPress install. If you're working on a plugin, you likely need to pass `--env-cwd` to make sure composer/phpunit commands are executed relative to the plugin you're working on. For example, `wp-env run cli --env-cwd=wp-content/plugins/gutenberg composer install`.
 
-### Customizing the `wp-tests-config.php` file
+To make this easier, it's often helpful to add scripts in your `package.json` file:
 
-While we do provide a default `wp-tests-config.php` file within the environment, there may be cases where you want to use your own. WordPress provides a `WP_TESTS_CONFIG_FILE_PATH` constant that you can use to change the `wp-config.php` file used for testing. Set this to a desired path in your `bootstrap.php` file and the file you've chosen will be used instead of the one included in the environment.
+```json
+{
+	"scripts": {
+		"composer": "wp-env run cli --env-cwd=wp-content/plugins/gutenberg composer"
+	}
+}
+```
+
+Then, `npm run composer install` would run composer install in the environment. You could also do this for phpunit, wp-cli, etc.
 
 ## Using Xdebug
 
@@ -272,15 +273,14 @@ The start command installs and initializes the WordPress environment, which incl
 ```sh
 wp-env start
 
-Starts WordPress for development on port 8888 (override with WP_ENV_PORT) and
-tests on port 8889 (override with WP_ENV_TESTS_PORT). The current working
-directory must be a WordPress installation, a plugin, a theme, or contain a
-.wp-env.json file. After first install, use the '--update' flag to download
-updates to mapped sources and to re-apply WordPress configuration options.
+Starts WordPress for development on port 8888 (​http://localhost:8888​)
+(override with WP_ENV_PORT) and tests on port 8889 (​http://localhost:8889​)
+(override with WP_ENV_TESTS_PORT). The current working directory must be a
+WordPress installation, a plugin, a theme, or contain a .wp-env.json file. After
+first install, use the '--update' flag to download updates to mapped sources and
+to re-apply WordPress configuration options.
 
 Options:
-  --help     Show help                                                 [boolean]
-  --version  Show version number                                       [boolean]
   --debug    Enable debug output.                     [boolean] [default: false]
   --update   Download source updates and apply WordPress configuration.
                                                       [boolean] [default: false]
@@ -289,6 +289,7 @@ Options:
              them in a comma-separated list: `--xdebug=develop,coverage`. See
              https://xdebug.org/docs/all_settings#mode for information about
              Xdebug modes.                                              [string]
+  --scripts  Execute any configured lifecycle scripts. [boolean] [default: true]
 ```
 
 ### `wp-env stop`
@@ -297,6 +298,9 @@ Options:
 wp-env stop
 
 Stops running WordPress for development and tests and frees the ports.
+
+Options:
+  --debug            Enable debug output.             [boolean] [default: false]
 ```
 
 ### `wp-env clean [environment]`
@@ -309,6 +313,10 @@ Cleans the WordPress databases.
 Positionals:
   environment  Which environments' databases to clean.
             [string] [choices: "all", "development", "tests"] [default: "tests"]
+
+Options:
+  --debug    Enable debug output.                     [boolean] [default: false]
+  --scripts  Execute any configured lifecycle scripts. [boolean] [default: true]
 ```
 
 ### `wp-env run [container] [command]`
@@ -322,9 +330,10 @@ back to using quotation marks; <code>wp-env</code> considers everything inside t
 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.
@@ -346,8 +355,6 @@ Positionals:
   command    The command to run.                           [array] [default: []]
 
 Options:
-  --help     Show help                                                 [boolean]
-  --version  Show version number                                       [boolean]
   --debug    Enable debug output.                     [boolean] [default: false]
   --env-cwd  The command's working directory inside of the container. Paths
              without a leading slash are relative to the WordPress root.
@@ -409,11 +416,22 @@ Success: Installed 1 of 1 plugins.
 ✔ Ran `plugin install custom-post-type-ui` in 'cli'. (in 6s 483ms)
 ```
 
-**NOTE**: Depending on your host OS, you may experience errors when trying to install plugins or themes (e.g. `Warning: Could not create directory.`). This is typically because the user ID used within the container does not have write access to the mounted directories created by `wp-env`. To resolve this, run the `docker-compose` command directly from the directory created by `wp-env` and add `-u $(id -u)` and `-e HOME=/tmp` the `run` command as options:
+#### Changing the permalink structure
 
-```sh
-$ cd ~/wp-env/500cd328b649d63e882d5c4695871d04
-$ docker-compose run --rm -u $(id -u) -e HOME=/tmp cli [plugin|theme] install <plugin|theme>
+You might want to do this to enable access to the REST API (`wp-env/wp/v2/`) endpoint in your wp-env environment. The endpoint is not available with plain permalinks.
+
+**Examples**
+
+To set the permalink to just the post name:
+
+```
+wp-env run cli "wp rewrite structure /%postname%/"
+```
+
+To set the permalink to the year, month, and post name:
+
+```
+wp-env run cli "wp rewrite structure /%year%/%monthnum%/%postname%/"
 ```
 
 ### `wp-env destroy`
@@ -423,6 +441,9 @@ wp-env destroy
 
 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]
 ```
 
 ### `wp-env logs [environment]`
@@ -437,15 +458,13 @@ Positionals:
       [string] [choices: "development", "tests", "all"] [default: "development"]
 
 Options:
-  --help     Show help                                                 [boolean]
-  --version  Show version number                                       [boolean]
   --debug    Enable debug output.                     [boolean] [default: false]
   --watch    Watch for logs as they happen.            [boolean] [default: true]
 ```
 
 ### `wp-env install-path`
 
-Outputs the absolute path to the WordPress environment files.
+Get the path where all of the environment files are stored. This includes the Docker files, WordPress, PHPUnit files, and any sources that were downloaded.
 
 Example:
 
@@ -540,9 +559,23 @@ 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.
 
-### Examples
+## 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
+
+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:
+
+-   `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.
 
-#### Latest stable WordPress + current directory as a plugin
+You can override the `afterSetup` option using the `WP_ENV_AFTER_SETUP` environment variable.
+
+## Examples
+
+### Latest stable WordPress + current directory as a plugin
 
 This is useful for plugin development.
 
@@ -564,7 +597,7 @@ This is useful for plugin development when upstream Core changes need to be test
 }
 ```
 
-#### Local `wordpress-develop` + current directory as a plugin
+### Local `wordpress-develop` + current directory as a plugin
 
 This is useful for working on plugins and WordPress Core at the same time.
 
@@ -586,7 +619,7 @@ If you are running `wordpress-develop` in a dev mode (e.g. the watch command `de
 }
 ```
 
-#### A complete testing environment
+### A complete testing environment
 
 This is useful for integration testing: that is, testing how old versions of WordPress and different combinations of plugins and themes impact each other.
 
@@ -598,7 +631,7 @@ This is useful for integration testing: that is, testing how old versions of Wor
 }
 ```
 
-#### Add mu-plugins and other mapped directories
+### Add mu-plugins and other mapped directories
 
 You can add mu-plugins via the mapping config. The mapping config also allows you to mount a directory to any location in the wordpress install, so you could even mount a subdirectory. Note here that theme-1, will not be activated.
 
@@ -613,7 +646,7 @@ You can add mu-plugins via the mapping config. The mapping config also allows yo
 }
 ```
 
-#### Avoid activating plugins or themes on the instance
+### Avoid activating plugins or themes on the instance
 
 Since all plugins in the `plugins` key are activated by default, you should use the `mappings` key to avoid this behavior. This might be helpful if you have a test plugin that should not be activated all the time.
 
@@ -626,7 +659,7 @@ Since all plugins in the `plugins` key are activated by default, you should use
 }
 ```
 
-#### Map a plugin only in the tests environment
+### Map a plugin only in the tests environment
 
 If you need a plugin active in one environment but not the other, you can use `env.<envName>` to set options specific to one environment. Here, we activate cwd and a test plugin on the tests instance. This plugin is not activated on any other instances.
 
@@ -641,7 +674,7 @@ If you need a plugin active in one environment but not the other, you can use `e
 }
 ```
 
-#### Custom Port Numbers
+### Custom Port Numbers
 
 You can tell `wp-env` to use a custom port number so that your instance does not conflict with other `wp-env` instances.
 
@@ -657,7 +690,7 @@ You can tell `wp-env` to use a custom port number so that your instance does not
 }
 ```
 
-#### Specific PHP Version
+### Specific PHP Version
 
 You can tell `wp-env` to use a specific PHP version for compatibility and testing. This can also be set via the environment variable `WP_ENV_PHP_VERSION`.
 
@@ -668,6 +701,39 @@ You can tell `wp-env` to use a specific PHP version for compatibility and testin
 }
 ```
 
+### Node Lifecycle Script
+
+This is useful for performing some actions after setting up the environment, such as bootstrapping an E2E test environment.
+
+```json
+{
+	"afterSetup": "node tests/e2e/bin/setup-env.js"
+}
+```
+
+### Advanced PHP settings
+
+You can set PHP settings by mapping an `.htaccess` file. This maps an `.htaccess` file to the WordPress root (`/var/www/html`) from the directory in which you run `wp-env`.
+
+```json
+{
+	"mappings": {
+		".htaccess": ".htaccess"
+	}
+}
+```
+
+Then, your .htaccess file can contain various settings like this:
+
+```
+# Note: the default upload value is 1G.
+php_value post_max_size 2G
+php_value upload_max_filesize 2G
+php_value memory_limit 2G
+```
+
+This is useful if there are options you'd like to add to `php.ini`, which is difficult to access in this environment.
+
 ## Contributing to this package
 
 This is an individual package that's part of the Gutenberg project. The project is organized as a monorepo. It's made up of multiple self-contained software packages, each with a specific purpose. The packages in this monorepo are published to [npm](https://www.npmjs.com/) and used by [WordPress](https://make.wordpress.org/core/) as well as other software projects.

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

@@ -10,25 +10,28 @@ const path = require( 'path' );
  */
 const { hasSameCoreSource } = require( './wordpress' );
 const { dbEnv } = require( './config' );
+const getHostUser = require( './get-host-user' );
 
 /**
  * @typedef {import('./config').WPConfig} WPConfig
- * @typedef {import('./config').WPServiceConfig} WPServiceConfig
+ * @typedef {import('./config').WPEnvironmentConfig} WPEnvironmentConfig
  */
 
 /**
  * Gets the volume mounts for an individual service.
  *
- * @param {string}          workDirectoryPath The working directory for wp-env.
- * @param {WPServiceConfig} config            The service config to get the mounts from.
- * @param {string}          wordpressDefault  The default internal path for the WordPress
- *                                            source code (such as tests-wordpress).
+ * @param {string}              workDirectoryPath The working directory for wp-env.
+ * @param {WPEnvironmentConfig} config            The service config to get the mounts from.
+ * @param {string}              hostUsername      The username of the host running wp-env.
+ * @param {string}              wordpressDefault  The default internal path for the WordPress
+ *                                                source code (such as tests-wordpress).
  *
  * @return {string[]} An array of volumes to mount in string format.
  */
 function getMounts(
 	workDirectoryPath,
 	config,
+	hostUsername,
 	wordpressDefault = 'wordpress'
 ) {
 	// Top-level WordPress directory mounts (like wp-content/themes)
@@ -46,9 +49,10 @@ function getMounts(
 			`${ source.path }:/var/www/html/wp-content/themes/${ source.basename }`
 	);
 
-	const coreMount = `${
-		config.coreSource ? config.coreSource.path : wordpressDefault
-	}:/var/www/html`;
+	const userHomeMount =
+		wordpressDefault === 'wordpress'
+			? `user-home:/home/${ hostUsername }`
+			: `tests-user-home:/home/${ hostUsername }`;
 
 	const corePHPUnitMount = `${ path.join(
 		workDirectoryPath,
@@ -59,10 +63,15 @@ function getMounts(
 		'phpunit'
 	) }:/wordpress-phpunit`;
 
+	const coreMount = `${
+		config.coreSource ? config.coreSource.path : wordpressDefault
+	}:/var/www/html`;
+
 	return [
 		...new Set( [
-			coreMount,
+			coreMount, // Must be first because of some operations later that expect it to be!
 			corePHPUnitMount,
+			userHomeMount,
 			...directoryMounts,
 			...pluginMounts,
 			...themeMounts,
@@ -79,16 +88,32 @@ function getMounts(
  * @return {Object} A docker-compose config object, ready to serialize into YAML.
  */
 module.exports = function buildDockerComposeConfig( config ) {
+	// Since we are mounting files from the host operating system
+	// we want to create the host user in some of our containers.
+	// This ensures ownership parity and lets us access files
+	// and folders between the containers and the host.
+	const hostUser = getHostUser();
+
 	const developmentMounts = getMounts(
 		config.workDirectoryPath,
-		config.env.development
+		config.env.development,
+		hostUser.name
 	);
 	const testsMounts = getMounts(
 		config.workDirectoryPath,
 		config.env.tests,
+		hostUser.name,
 		'tests-wordpress'
 	);
 
+	// We use a custom Dockerfile in order to make sure that
+	// the current host user exists inside the container.
+	const imageBuildArgs = {
+		HOST_USERNAME: hostUser.name,
+		HOST_UID: hostUser.uid,
+		HOST_GID: hostUser.gid,
+	};
+
 	// When both tests and development reference the same WP source, we need to
 	// ensure that tests pulls from a copy of the files so that it maintains
 	// a separate DB and config. Additionally, if the source type is local we
@@ -143,64 +168,6 @@ module.exports = function buildDockerComposeConfig( config ) {
 	const developmentPorts = `\${WP_ENV_PORT:-${ config.env.development.port }}:80`;
 	const testsPorts = `\${WP_ENV_TESTS_PORT:-${ config.env.tests.port }}:80`;
 
-	// Set the WordPress, WP-CLI, PHPUnit PHP version if defined.
-	const developmentPhpVersion = config.env.development.phpVersion
-		? config.env.development.phpVersion
-		: '';
-	const testsPhpVersion = config.env.tests.phpVersion
-		? config.env.tests.phpVersion
-		: '';
-
-	// Set the WordPress images with the PHP version tag.
-	const developmentWpImage = `wordpress${
-		developmentPhpVersion ? ':php' + developmentPhpVersion : ''
-	}`;
-	const testsWpImage = `wordpress${
-		testsPhpVersion ? ':php' + testsPhpVersion : ''
-	}`;
-	// Set the WordPress CLI images with the PHP version tag.
-	const developmentWpCliImage = `wordpress:cli${
-		! developmentPhpVersion || developmentPhpVersion.length === 0
-			? ''
-			: '-php' + developmentPhpVersion
-	}`;
-	const testsWpCliImage = `wordpress:cli${
-		! testsPhpVersion || testsPhpVersion.length === 0
-			? ''
-			: '-php' + testsPhpVersion
-	}`;
-
-	// Defaults are to use the most recent version of PHPUnit that provides
-	// support for the specified version of PHP.
-	// PHP Unit is assumed to be for Tests so use the testsPhpVersion.
-	let phpunitTag = 'latest';
-	const phpunitPhpVersion = '-php-' + testsPhpVersion + '-fpm';
-	if ( testsPhpVersion === '5.6' ) {
-		phpunitTag = '5' + phpunitPhpVersion;
-	} else if ( testsPhpVersion === '7.0' ) {
-		phpunitTag = '6' + phpunitPhpVersion;
-	} else if ( testsPhpVersion === '7.1' ) {
-		phpunitTag = '7' + phpunitPhpVersion;
-	} else if ( testsPhpVersion === '7.2' ) {
-		phpunitTag = '8' + phpunitPhpVersion;
-	} else if (
-		[ '7.3', '7.4', '8.0', '8.1', '8.2' ].indexOf( testsPhpVersion ) >= 0
-	) {
-		phpunitTag = '9' + phpunitPhpVersion;
-	}
-	const phpunitImage = `wordpressdevelop/phpunit:${ phpunitTag }`;
-
-	// The www-data user in wordpress:cli has a different UID (82) to the
-	// www-data user in wordpress (33). Ensure we use the wordpress www-data
-	// user for CLI commands.
-	// https://github.com/docker-library/wordpress/issues/256
-	const cliUser = '33:33';
-
-	// If the user mounted their own uploads folder, we should not override it in the phpunit service.
-	const isMappingTestUploads = testsMounts.some( ( mount ) =>
-		mount.endsWith( ':/var/www/html/wp-content/uploads' )
-	);
-
 	return {
 		version: '3.7',
 		services: {
@@ -227,69 +194,72 @@ module.exports = function buildDockerComposeConfig( config ) {
 				volumes: [ 'mysql-test:/var/lib/mysql' ],
 			},
 			wordpress: {
-				build: '.',
 				depends_on: [ 'mysql' ],
-				image: developmentWpImage,
+				build: {
+					context: '.',
+					dockerfile: 'WordPress.Dockerfile',
+					args: imageBuildArgs,
+				},
 				ports: [ developmentPorts ],
 				environment: {
+					APACHE_RUN_USER: '#' + hostUser.uid,
+					APACHE_RUN_GROUP: '#' + hostUser.gid,
 					...dbEnv.credentials,
 					...dbEnv.development,
 					WP_TESTS_DIR: '/wordpress-phpunit',
 				},
 				volumes: developmentMounts,
+				extra_hosts: [ 'host.docker.internal:host-gateway' ],
 			},
 			'tests-wordpress': {
 				depends_on: [ 'tests-mysql' ],
-				image: testsWpImage,
+				build: {
+					context: '.',
+					dockerfile: 'Tests-WordPress.Dockerfile',
+					args: imageBuildArgs,
+				},
 				ports: [ testsPorts ],
 				environment: {
+					APACHE_RUN_USER: '#' + hostUser.uid,
+					APACHE_RUN_GROUP: '#' + hostUser.gid,
 					...dbEnv.credentials,
 					...dbEnv.tests,
 					WP_TESTS_DIR: '/wordpress-phpunit',
 				},
 				volumes: testsMounts,
+				extra_hosts: [ 'host.docker.internal:host-gateway' ],
 			},
 			cli: {
 				depends_on: [ 'wordpress' ],
-				image: developmentWpCliImage,
+				build: {
+					context: '.',
+					dockerfile: 'CLI.Dockerfile',
+					args: imageBuildArgs,
+				},
 				volumes: developmentMounts,
-				user: cliUser,
+				user: hostUser.fullUser,
 				environment: {
 					...dbEnv.credentials,
 					...dbEnv.development,
 					WP_TESTS_DIR: '/wordpress-phpunit',
 				},
+				extra_hosts: [ 'host.docker.internal:host-gateway' ],
 			},
 			'tests-cli': {
 				depends_on: [ 'tests-wordpress' ],
-				image: testsWpCliImage,
+				build: {
+					context: '.',
+					dockerfile: 'Tests-CLI.Dockerfile',
+					args: imageBuildArgs,
+				},
 				volumes: testsMounts,
-				user: cliUser,
+				user: hostUser.fullUser,
 				environment: {
 					...dbEnv.credentials,
 					...dbEnv.tests,
 					WP_TESTS_DIR: '/wordpress-phpunit',
 				},
-			},
-			composer: {
-				image: 'composer',
-				volumes: [ `${ config.configDirectoryPath }:/app` ],
-			},
-			phpunit: {
-				image: phpunitImage,
-				depends_on: [ 'tests-wordpress' ],
-				volumes: [
-					...testsMounts,
-					...( ! isMappingTestUploads
-						? [ 'phpunit-uploads:/var/www/html/wp-content/uploads' ]
-						: [] ),
-				],
-				environment: {
-					LOCAL_DIR: 'html',
-					WP_TESTS_DIR: '/wordpress-phpunit',
-					...dbEnv.credentials,
-					...dbEnv.tests,
-				},
+				extra_hosts: [ 'host.docker.internal:host-gateway' ],
 			},
 		},
 		volumes: {
@@ -297,7 +267,8 @@ module.exports = function buildDockerComposeConfig( config ) {
 			...( ! config.env.tests.coreSource && { 'tests-wordpress': {} } ),
 			mysql: {},
 			'mysql-test': {},
-			'phpunit-uploads': {},
+			'user-home': {},
+			'tests-user-home': {},
 		},
 	};
 };

package/lib/cache.js

@@ -1,3 +1,4 @@
+'use strict';
 /**
  * External dependencies
  */

package/lib/cli.js

@@ -39,8 +39,11 @@ const withSpinner =
 				process.exit( 0 );
 			},
 			( error ) => {
-				if ( error instanceof env.ValidationError ) {
-					// Error is a validation error. That means the user did something wrong.
+				if (
+					error instanceof env.ValidationError ||
+					error instanceof env.AfterSetupError
+				) {
+					// Error is a configuration error. That means the user did something wrong.
 					spinner.fail( error.message );
 					process.exit( 1 );
 				} else if (
@@ -124,6 +127,11 @@ module.exports = function cli() {
 				coerce: parseXdebugMode,
 				type: 'string',
 			} );
+			args.option( 'scripts', {
+				type: 'boolean',
+				describe: 'Execute any configured lifecycle scripts.',
+				default: true,
+			} );
 		},
 		withSpinner( env.start )
 	);
@@ -145,6 +153,11 @@ module.exports = function cli() {
 				choices: [ 'all', 'development', 'tests' ],
 				default: 'tests',
 			} );
+			args.option( 'scripts', {
+				type: 'boolean',
+				describe: 'Execute any configured lifecycle scripts.',
+				default: true,
+			} );
 		},
 		withSpinner( env.clean )
 	);
@@ -215,7 +228,7 @@ module.exports = function cli() {
 	);
 	yargs.command(
 		'install-path',
-		'Get the path where environment files are located.',
+		'Get the path where all of the environment files are stored. This includes the Docker files, WordPress, PHPUnit files, and any sources that were downloaded.',
 		() => {},
 		withSpinner( env.installPath )
 	);

package/lib/commands/clean.js

@@ -1,3 +1,4 @@
+'use strict';
 /**
  * External dependencies
  */
@@ -8,6 +9,7 @@ const dockerCompose = require( 'docker-compose' );
  */
 const initConfig = require( '../init-config' );
 const { configureWordPress, resetDatabase } = require( '../wordpress' );
+const { executeAfterSetup } = require( '../execute-after-setup' );
 
 /**
  * @typedef {import('../wordpress').WPEnvironment} WPEnvironment
@@ -20,9 +22,15 @@ const { configureWordPress, resetDatabase } = require( '../wordpress' );
  * @param {Object}                 options
  * @param {WPEnvironmentSelection} options.environment The environment to clean. Either 'development', 'tests', or 'all'.
  * @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 clean( { environment, spinner, debug } ) {
+module.exports = async function clean( {
+	environment,
+	spinner,
+	scripts,
+	debug,
+} ) {
 	const config = await initConfig( { spinner, debug } );
 
 	const description = `${ environment } environment${
@@ -57,5 +65,10 @@ module.exports = async function clean( { environment, spinner, debug } ) {
 
 	await Promise.all( tasks );
 
+	// Execute any configured command that should run after the environment has finished being set up.
+	if ( scripts ) {
+		executeAfterSetup( config, spinner );
+	}
+
 	spinner.text = `Cleaned ${ description }.`;
 };