@wordpress/env 4.1.2 → 4.2.1

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## Unreleased
 
+## 4.2.0 (2022-01-27)
+
+### Enhancement
+-   Added command `wp-env install-path` to list the directory used for the environment.
+-   The help entry is now shown when no subcommand is passed to `wp-env`.
+
+### Bug Fix
+-   Updated `yargs` to fix [CVE-2021-3807](https://nvd.nist.gov/vuln/detail/CVE-2021-3807).
+
+## 4.1.3 (2021-11-07)
+
+### Bug Fix
+
+-   Fix Xdebug installation code to ensure it would fail gracefully
+
 ## 4.0.3 (2021-04-29)
 
 ### Bug Fix

package/LICENSE.md

@@ -1,6 +1,6 @@
 ## Gutenberg
 
-    Copyright 2016-2021 by the contributors
+    Copyright 2016-2022 by the contributors
 
 **License for Contributions (on and after April 15, 2021)**
 

package/README.md

@@ -400,6 +400,18 @@ Options:
   --watch    Watch for logs as they happen.            [boolean] [default: true]
 ```
 
+### `wp-env install-path`
+
+Outputs the absolute path to the WordPress environment files.
+
+Example:
+
+```sh
+$ wp-env install-path
+
+/home/user/.wp-env/63263e6506becb7b8613b02d42280a49
+```
+
 ## .wp-env.json
 
 You can customize the WordPress installation, plugins and themes that the development environment will use by specifying a `.wp-env.json` file in the directory that you run `wp-env` from.
@@ -509,6 +521,8 @@ This is useful for plugin development when upstream Core changes need to be test
 
 This is useful for working on plugins and WordPress Core at the same time.
 
+If you are running a _build_ of `wordpress-develop`, point `core` to the `build` directory.
+
 ```json
 {
 	"core": "../wordpress-develop/build",
@@ -516,6 +530,15 @@ This is useful for working on plugins and WordPress Core at the same time.
 }
 ```
 
+If you are running `wordpress-develop` in a dev mode (e.g. the watch command `dev` or the dev build `build:dev`), then point `core` to the `src` directory.
+
+```json
+{
+	"core": "../wordpress-develop/src",
+	"plugins": [ "." ]
+}
+```
+
 #### 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,4 +621,10 @@ You can tell `wp-env` to use a specific PHP version for compatibility and testin
 }
 ```
 
-<br/><br/><p align="center"><img src="https://s.w.org/style/images/codeispoetry.png?1" alt="Code is Poetry." /></p>
+## 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.
+
+To find out more about contributing to this package or Gutenberg as a whole, please read the project's main [contributor guide](https://github.com/WordPress/gutenberg/tree/HEAD/CONTRIBUTING.md).
+
+<br /><br /><p align="center"><img src="https://s.w.org/style/images/codeispoetry.png?1" alt="Code is Poetry." /></p>

package/bin/wp-env

@@ -1,3 +1,4 @@
 #!/usr/bin/env node
 'use strict';
-require( '../lib/cli' )().parse( process.argv.slice( 2 ) );
+const command = process.argv.slice( 2 );
+require( '../lib/cli' )().parse( command.length ? command : [ '--help' ] );

package/lib/cli.js

@@ -197,6 +197,12 @@ module.exports = function cli() {
 		() => {},
 		withSpinner( env.destroy )
 	);
+	yargs.command(
+		'install-path',
+		'Get the path where environment files are located.',
+		() => {},
+		withSpinner( env.installPath )
+	);
 
 	return yargs;
 };

package/lib/commands/index.js

@@ -7,6 +7,7 @@ const clean = require( './clean' );
 const run = require( './run' );
 const destroy = require( './destroy' );
 const logs = require( './logs' );
+const installPath = require( './install-path' );
 
 module.exports = {
 	start,
@@ -15,4 +16,5 @@ module.exports = {
 	run,
 	destroy,
 	logs,
+	installPath,
 };

package/lib/commands/install-path.js

@@ -0,0 +1,20 @@
+/**
+ * Internal dependencies
+ */
+const initConfig = require( '../init-config' );
+
+/**
+ * Logs the path to where wp-env files are installed.
+ *
+ * @param {Object}  options
+ * @param {Object}  options.spinner
+ * @param {boolean} options.debug
+ */
+module.exports = async function installPath( { spinner, debug } ) {
+	// Stop the spinner so that stdout is not polluted.
+	spinner.stop();
+	// initConfig will fail if wp-env start has not yet been called, so that
+	// edge case is handled.
+	const { workDirectoryPath } = await initConfig( { spinner, debug } );
+	console.log( workDirectoryPath );
+};

package/lib/commands/start.js

@@ -174,6 +174,7 @@ module.exports = async function start( { spinner, debug, update, xdebug } ) {
 
 	const siteUrl = config.env.development.config.WP_SITEURL;
 	const e2eSiteUrl = config.env.tests.config.WP_TESTS_DOMAIN;
+
 	const { out: mySQLAddress } = await dockerCompose.port(
 		'mysql',
 		3306,
@@ -181,6 +182,13 @@ module.exports = async function start( { spinner, debug, update, xdebug } ) {
 	);
 	const mySQLPort = mySQLAddress.split( ':' ).pop();
 
+	const { out: testsMySQLAddress } = await dockerCompose.port(
+		'tests-mysql',
+		3306,
+		dockerComposeConfig
+	);
+	const testsMySQLPort = testsMySQLAddress.split( ':' ).pop();
+
 	spinner.prefixText = 'WordPress development site started'
 		.concat( siteUrl ? ` at ${ siteUrl }` : '.' )
 		.concat( '\n' )
@@ -188,6 +196,9 @@ module.exports = async function start( { spinner, debug, update, xdebug } ) {
 		.concat( e2eSiteUrl ? ` at ${ e2eSiteUrl }` : '.' )
 		.concat( '\n' )
 		.concat( `MySQL is listening on port ${ mySQLPort }` )
+		.concat(
+			`MySQL for automated testing is listening on port ${ testsMySQLPort }`
+		)
 		.concat( '\n' );
 
 	spinner.text = 'Done!';

package/lib/config/test/config.js

@@ -1,4 +1,4 @@
-/* eslint-disable jest/no-try-expect, jest/no-conditional-expect */
+/* eslint-disable jest/no-conditional-expect */
 /**
  * External dependencies
  */
@@ -1128,4 +1128,4 @@ async function testPortNumberValidation( portName, value, envText = '' ) {
 	}
 	jest.clearAllMocks();
 }
-/* eslint-enable jest/no-try-expect, jest/no-conditional-expect */
+/* eslint-enable jest/no-conditional-expect */

package/lib/init-config.js

@@ -98,6 +98,41 @@ module.exports = async function initConfig( {
 	return config;
 };
 
+/**
+ * Checks the configured PHP version
+ * against the minimum version supported by Xdebug
+ *
+ * @param {WPConfig} config
+ * @return {boolean} Whether the PHP version is supported by Xdebug
+ */
+function checkXdebugPhpCompatibility( config ) {
+	// By default, an undefined phpVersion uses the version on the docker image,
+	// which is supported by Xdebug 3.
+	const phpCompatibility = true;
+
+	// If PHP version is defined
+	// ensure it meets the Xdebug minimum compatibility requirment
+	if ( config.env.development.phpVersion ) {
+		const versionTokens = config.env.development.phpVersion.split( '.' );
+		const majorVer = parseInt( versionTokens[ 0 ] );
+		const minorVer = parseInt( versionTokens[ 1 ] );
+
+		if ( isNaN( majorVer ) || isNaN( minorVer ) ) {
+			throw new Error(
+				'Something went wrong when parsing the PHP version.'
+			);
+		}
+
+		// Xdebug 3 supports 7.2 and higher
+		// Ensure user has specified a compatible PHP version
+		if ( majorVer < 7 || ( majorVer === 7 && minorVer < 2 ) ) {
+			throw new Error( 'Cannot use XDebug 3 on PHP < 7.2.' );
+		}
+	}
+
+	return phpCompatibility;
+}
+
 /**
  * Generates the Dockerfile used by wp-env's development instance.
  *
@@ -107,20 +142,14 @@ module.exports = async function initConfig( {
  * @return {string} The dockerfile contents.
  */
 function dockerFileContents( image, config ) {
-	let shouldInstallXdebug = true;
-	// By default, an undefined phpVersion uses the version on the docker image,
-	// which is supported by Xdebug 3.
-	if ( config.env.development.phpVersion ) {
-		const versionTokens = config.env.development.phpVersion.split( '.' );
-		const majorVersion = parseInt( versionTokens[ 0 ] );
-		const minorVersion = parseInt( versionTokens[ 1 ] );
-		if ( isNaN( majorVersion ) || isNaN( minorVersion ) ) {
-			throw new Error( 'Something went wrong parsing the php version.' );
-		}
+	// Don't install XDebug unless it is explicitly required
+	let shouldInstallXdebug = false;
+
+	if ( config.xdebug !== 'off' ) {
+		const usingCompatiblePhp = checkXdebugPhpCompatibility( config );
 
-		// Disable Xdebug for PHP < 7.2. Xdebug 3 supports 7.2 and higher.
-		if ( majorVersion < 7 || ( majorVersion === 7 && minorVersion < 2 ) ) {
-			shouldInstallXdebug = false;
+		if ( usingCompatiblePhp ) {
+			shouldInstallXdebug = true;
 		}
 	}
 
@@ -140,7 +169,8 @@ function installXdebug( enableXdebug ) {
 
 	return `
 # Install Xdebug:
-RUN pecl install xdebug && docker-php-ext-enable xdebug
+RUN if [ -z "$(pecl list | grep xdebug)" ] ; then pecl install xdebug ; fi
+RUN docker-php-ext-enable xdebug
 RUN echo 'xdebug.start_with_request=yes' >> /usr/local/etc/php/php.ini
 RUN echo 'xdebug.mode=${ enableXdebug }' >> /usr/local/etc/php/php.ini
 RUN echo '${ clientDetectSettings }' >> /usr/local/etc/php/php.ini

package/lib/parse-xdebug-mode.js

@@ -4,28 +4,29 @@ const XDEBUG_MODES = [
 	'coverage',
 	'debug',
 	'gcstats',
+	'off',
 	'profile',
 	'trace',
 ];
 
 /**
- * Custom parsing for the Xdebug mode set via yargs. This function ensures two things:
- * 1. If the --xdebug flag was set by itself, default to 'debug'.
- * 2. If the --xdebug flag includes modes, make sure they are accepted by Xdebug.
+ * Custom parsing for the Xdebug mode set via yargs. This function ensures three things:
+ * 1. If the --xdebug flag was not set, set it to 'off'.
+ * 2. If the --xdebug flag was set by itself, default to 'debug'.
+ * 3. If the --xdebug flag includes modes, make sure they are accepted by Xdebug.
  *
- * Note: ideally, we would also have this handle the case where no xdebug flag
- * is set (and then turn Xdebug off). However, yargs does not pass 'undefined'
- * to the coerce callback, so we cannot handle that case here.
- *
- * @param {string} value The user-set mode of Xdebug
+ * @param {string|undefined} value The user-set mode of Xdebug; undefined if there is no --xdebug flag.
  * @return {string} The Xdebug mode to use with defaults applied.
  */
 module.exports = function parseXdebugMode( value ) {
+	if ( value === undefined ) {
+		return 'off';
+	}
 	if ( typeof value !== 'string' ) {
 		throwXdebugModeError( value );
 	}
 
-	if ( value.length === 0 ) {
+	if ( value.length === 0 || value === 'undefined' ) {
 		return 'debug';
 	}
 

package/lib/wordpress.js

@@ -42,7 +42,20 @@ async function checkDatabaseConnection( { dockerComposeConfigPath, debug } ) {
  * @param {Object}        spinner     A CLI spinner which indicates progress.
  */
 async function configureWordPress( environment, config, spinner ) {
-	const installCommand = `wp core install --url="localhost:${ config.env[ environment ].port }" --title="${ config.name }" --admin_user=admin --admin_password=password --admin_email=wordpress@example.com --skip-email`;
+	const url = ( () => {
+		const port = config.env[ environment ].port;
+		const domain =
+			environment === 'tests'
+				? config.env.tests.config.WP_TESTS_DOMAIN
+				: config.env.development.config.WP_SITEURL;
+		if ( port === 80 ) {
+			return domain;
+		}
+
+		return `${ domain }:${ port }`;
+	} )();
+
+	const installCommand = `wp core install --url="${ url }" --title="${ config.name }" --admin_user=admin --admin_password=password --admin_email=wordpress@example.com --skip-email`;
 
 	// -eo pipefail exits the command as soon as anything fails in bash.
 	const setupCommands = [ 'set -eo pipefail', installCommand ];

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wordpress/env",
-	"version": "4.1.2",
+	"version": "4.2.1",
 	"description": "A zero-config, self contained local WordPress environment for development and testing.",
 	"author": "The WordPress Contributors",
 	"license": "GPL-2.0-or-later",
@@ -43,7 +43,7 @@
 		"rimraf": "^3.0.2",
 		"simple-git": "^2.35.0",
 		"terminal-link": "^2.0.0",
-		"yargs": "^14.0.0"
+		"yargs": "^17.3.0"
 	},
 	"publishConfig": {
 		"access": "public"
@@ -51,5 +51,5 @@
 	"scripts": {
 		"test": "echo \"Error: run tests from root\" && exit 1"
 	},
-	"gitHead": "8f7f052bc04e3f4eb50f479ced14be1489b9fa79"
+	"gitHead": "2e4922861e49f5a090f9dc52056165092cfba163"
 }