@wordpress/env 5.16.0 → 7.0.0

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 )
 	);
@@ -174,6 +187,13 @@ module.exports = function cli() {
 		'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.',
 		( args ) => {
+			args.option( 'env-cwd', {
+				type: 'string',
+				requiresArg: true,
+				default: '.',
+				describe:
+					"The command's working directory inside of the container. Paths without a leading slash are relative to the WordPress root.",
+			} );
 			args.positional( 'container', {
 				type: 'string',
 				describe: 'The container to run the command on.',
@@ -208,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 }.`;
 };

package/lib/commands/destroy.js

@@ -1,3 +1,4 @@
+'use strict';
 /**
  * External dependencies
  */
@@ -11,12 +12,11 @@ const inquirer = require( 'inquirer' );
  * Promisified dependencies
  */
 const rimraf = util.promisify( require( 'rimraf' ) );
-const exec = util.promisify( require( 'child_process' ).exec );
 
 /**
  * Internal dependencies
  */
-const { readConfig } = require( '../../lib/config' );
+const { loadConfig } = require( '../config' );
 
 /**
  * Destroy the development server.
@@ -26,9 +26,8 @@ const { readConfig } = require( '../../lib/config' );
  * @param {boolean} options.debug   True if debug mode is enabled.
  */
 module.exports = async function destroy( { spinner, debug } ) {
-	const configPath = path.resolve( '.wp-env.json' );
-	const { dockerComposeConfigPath, workDirectoryPath } = await readConfig(
-		configPath
+	const { dockerComposeConfigPath, workDirectoryPath } = await loadConfig(
+		path.resolve( '.' )
 	);
 
 	try {
@@ -39,7 +38,7 @@ module.exports = async function destroy( { spinner, debug } ) {
 	}
 
 	spinner.info(
-		'WARNING! This will remove Docker containers, volumes, and networks associated with the WordPress instance.'
+		'WARNING! This will remove Docker containers, volumes, networks, and images associated with the WordPress instance.'
 	);
 
 	const { yesDelete } = await inquirer.prompt( [
@@ -58,44 +57,20 @@ module.exports = async function destroy( { spinner, debug } ) {
 		return;
 	}
 
-	spinner.text = 'Removing WordPress docker containers.';
+	spinner.text = 'Removing docker images, volumes, and networks.';
 
-	await dockerCompose.rm( {
+	await dockerCompose.down( {
 		config: dockerComposeConfigPath,
-		commandOptions: [ '--stop', '-v' ],
+		commandOptions: [ '--volumes', '--remove-orphans', '--rmi', 'all' ],
 		log: debug,
 	} );
 
-	const directoryHash = path.basename( workDirectoryPath );
-
-	spinner.text = 'Removing docker volumes.';
-	await removeDockerItems( 'volume', directoryHash );
-
-	spinner.text = 'Removing docker networks.';
-	await removeDockerItems( 'network', directoryHash );
-
 	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.
+	await new Promise( ( resolve ) => setTimeout( resolve, 10000 ) );
 	await rimraf( workDirectoryPath );
 
 	spinner.text = 'Removed WordPress environment.';
 };
-
-/**
- * Removes docker items, like networks or volumes, matching the given name.
- *
- * @param {string} itemType The item type, like "network" or "volume"
- * @param {string} name     Remove items whose name match this string.
- */
-async function removeDockerItems( itemType, name ) {
-	const { stdout: items } = await exec(
-		`docker ${ itemType } ls -q --filter name=${ name }`
-	);
-	if ( items ) {
-		await exec(
-			`docker ${ itemType } rm ${ items
-				.split( '\n' ) // TODO: use os.EOL?
-				.join( ' ' ) }`
-		);
-	}
-}

package/lib/commands/index.js

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

package/lib/commands/install-path.js

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

package/lib/commands/logs.js

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

package/lib/commands/run.js

@@ -1,12 +1,16 @@
+'use strict';
 /**
  * External dependencies
  */
 const { spawn } = require( 'child_process' );
+const path = require( 'path' );
 
 /**
  * Internal dependencies
  */
 const initConfig = require( '../init-config' );
+const getHostUser = require( '../get-host-user' );
+const { ValidationError } = require( '../config' );
 
 /**
  * @typedef {import('../config').WPConfig} WPConfig
@@ -18,10 +22,19 @@ const initConfig = require( '../init-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.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.
  */
-module.exports = async function run( { container, command, spinner, debug } ) {
+module.exports = async function run( {
+	container,
+	command,
+	envCwd,
+	spinner,
+	debug,
+} ) {
+	validateContainerExistence( container );
+
 	const config = await initConfig( { spinner, debug } );
 
 	command = command.join( ' ' );
@@ -29,31 +42,82 @@ module.exports = async function run( { container, command, spinner, debug } ) {
 	// Shows a contextual tip for the given command.
 	showCommandTips( command, container, spinner );
 
-	await spawnCommandDirectly( {
-		container,
-		command,
-		spinner,
-		config,
-	} );
+	await spawnCommandDirectly( config, container, command, envCwd, spinner );
 
 	spinner.text = `Ran \`${ command }\` 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 {Object}   options
- * @param {string}   options.container The Docker container to run the command on.
- * @param {string}   options.command   The command to run.
- * @param {WPConfig} options.config    The wp-env configuration.
- * @param {Object}   options.spinner   A CLI spinner which indicates progress.
+ * @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}   envCwd    The working directory for the command to be executed from.
+ * @param {Object}   spinner   A CLI spinner which indicates progress.
  */
-function spawnCommandDirectly( { container, command, config, spinner } ) {
+function spawnCommandDirectly( config, container, command, envCwd, spinner ) {
+	// Both the `wordpress` and `tests-wordpress` containers have the host's
+	// user so that they can maintain ownership parity with the host OS.
+	// We should run any commands as that user so that they are able
+	// to interact with the files mounted from the host.
+	const hostUser = getHostUser();
+
+	// We need to pass absolute paths to the container.
+	envCwd = path.resolve(
+		// Not all containers have the same starting working directory.
+		container === 'mysql' || container === 'tests-mysql'
+			? '/'
+			: '/var/www/html',
+		envCwd
+	);
+
+	const isTTY = process.stdout.isTTY;
 	const composeCommand = [
 		'-f',
 		config.dockerComposeConfigPath,
-		'run',
-		'--rm',
+		'exec',
+		! isTTY ? '-T' : '',
+		'-w',
+		envCwd,
+		'--user',
+		hostUser.fullUser,
 		container,
 		...command.split( ' ' ), // The command will fail if passed as a complete string.
 	];