From 2a80bf443392b9aaac6157335984d80d1a5f7c14 Mon Sep 17 00:00:00 2001
From: Noah Allen <noahtallen@gmail.com>
Date: Fri, 27 Nov 2020 16:45:49 -0800
Subject: [PATCH 01/15] Install xDebug in wp-env

---
 .../env/lib/build-docker-compose-config.js    |  1 +
 packages/env/lib/init-config.js               | 24 +++++++++++++++++++
 2 files changed, 25 insertions(+)

diff --git a/packages/env/lib/build-docker-compose-config.js b/packages/env/lib/build-docker-compose-config.js
index b569d6df41fd2c..8f97225a7a1b08 100644
--- a/packages/env/lib/build-docker-compose-config.js
+++ b/packages/env/lib/build-docker-compose-config.js
@@ -176,6 +176,7 @@ module.exports = function buildDockerComposeConfig( config ) {
 				volumes: [ 'mysql:/var/lib/mysql' ],
 			},
 			wordpress: {
+				build: '.',
 				depends_on: [ 'mysql' ],
 				image: developmentWpImage,
 				ports: [ developmentPorts ],
diff --git a/packages/env/lib/init-config.js b/packages/env/lib/init-config.js
index 02f4f3ed5e6cd7..944cfdd4fe5766 100644
--- a/packages/env/lib/init-config.js
+++ b/packages/env/lib/init-config.js
@@ -38,6 +38,15 @@ module.exports = async function initConfig( { spinner, debug } ) {
 		yaml.dump( dockerComposeConfig )
 	);
 
+	const xDebugMode = 'debug';
+	await fs.writeFile(
+		path.resolve( config.workDirectoryPath, 'Dockerfile' ),
+		dockerFileContents(
+			dockerComposeConfig.services.wordpress.image,
+			xDebugMode
+		)
+	);
+
 	if ( config.debug ) {
 		spinner.info(
 			`Config:\n${ JSON.stringify(
@@ -55,3 +64,18 @@ module.exports = async function initConfig( { spinner, debug } ) {
 
 	return config;
 };
+
+function dockerFileContents( image, xDebugMode ) {
+	return `
+FROM ${ image }
+
+RUN apt -qy install $PHPIZE_DEPS \\
+	&& pecl install xdebug \\
+	&& docker-php-ext-enable xdebug
+
+RUN touch /usr/local/etc/php/php.ini
+RUN echo 'xdebug.start_with_request=yes' >> /usr/local/etc/php/php.ini
+RUN echo 'xdebug.discover_client_host=1' >> /usr/local/etc/php/php.ini
+RUN echo 'xdebug.mode=${ xDebugMode }' >> /usr/local/etc/php/php.ini
+`;
+}

From 616f740b4940ed6fd1abadf1a70b8ccea706a603 Mon Sep 17 00:00:00 2001
From: Noah Allen <noahtallen@gmail.com>
Date: Wed, 2 Dec 2020 15:34:13 -0800
Subject: [PATCH 02/15] Fix client detect settings

---
 .vscode/launch.json             | 17 +++++++++++++++++
 lib/load.php                    |  1 +
 packages/env/lib/init-config.js | 20 +++++++++++++-------
 3 files changed, 31 insertions(+), 7 deletions(-)
 create mode 100644 .vscode/launch.json

diff --git a/.vscode/launch.json b/.vscode/launch.json
new file mode 100644
index 00000000000000..cf995dc21d1eac
--- /dev/null
+++ b/.vscode/launch.json
@@ -0,0 +1,17 @@
+{
+	// Use IntelliSense to learn about possible attributes.
+	// Hover to view descriptions of existing attributes.
+	// For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+	"version": "0.2.0",
+	"configurations": [
+		{
+			"name": "Listen for XDebug",
+			"type": "php",
+			"request": "launch",
+			"port": 9003,
+			"pathMappings": {
+				"/var/www/html/wp-content/plugins/gutenberg": "${workspaceRoot}/"
+			}
+		}
+	]
+}
\ No newline at end of file
diff --git a/lib/load.php b/lib/load.php
index 967c995ee413a8..cc9b320667fbba 100644
--- a/lib/load.php
+++ b/lib/load.php
@@ -5,6 +5,7 @@
  * @package gutenberg
  */
 
+// xdebug_info(); exit;
 if ( ! defined( 'ABSPATH' ) ) {
 	die( 'Silence is golden.' );
 }
diff --git a/packages/env/lib/init-config.js b/packages/env/lib/init-config.js
index 944cfdd4fe5766..af65dba46d0b1a 100644
--- a/packages/env/lib/init-config.js
+++ b/packages/env/lib/init-config.js
@@ -4,6 +4,7 @@
 const path = require( 'path' );
 const fs = require( 'fs' ).promises;
 const yaml = require( 'js-yaml' );
+const os = require( 'os' );
 
 /**
  * Internal dependencies
@@ -38,12 +39,12 @@ module.exports = async function initConfig( { spinner, debug } ) {
 		yaml.dump( dockerComposeConfig )
 	);
 
-	const xDebugMode = 'debug';
+	const XdebugMode = 'debug';
 	await fs.writeFile(
 		path.resolve( config.workDirectoryPath, 'Dockerfile' ),
 		dockerFileContents(
 			dockerComposeConfig.services.wordpress.image,
-			xDebugMode
+			XdebugMode
 		)
 	);
 
@@ -65,9 +66,14 @@ module.exports = async function initConfig( { spinner, debug } ) {
 	return config;
 };
 
-function dockerFileContents( image, xDebugMode ) {
-	return `
-FROM ${ image }
+function dockerFileContents( image, XdebugMode ) {
+	const isLinux = os.type() === 'Linux';
+	// Discover client host does not appear to work on macOS with Docker.
+	const clientDetectSettings = isLinux
+		? 'xdebug.discover_client_host=true'
+		: 'xdebug.client_host="host.docker.internal"';
+
+	return `FROM ${ image }
 
 RUN apt -qy install $PHPIZE_DEPS \\
 	&& pecl install xdebug \\
@@ -75,7 +81,7 @@ RUN apt -qy install $PHPIZE_DEPS \\
 
 RUN touch /usr/local/etc/php/php.ini
 RUN echo 'xdebug.start_with_request=yes' >> /usr/local/etc/php/php.ini
-RUN echo 'xdebug.discover_client_host=1' >> /usr/local/etc/php/php.ini
-RUN echo 'xdebug.mode=${ xDebugMode }' >> /usr/local/etc/php/php.ini
+RUN echo 'xdebug.mode=${ XdebugMode }' >> /usr/local/etc/php/php.ini
+RUN echo '${ clientDetectSettings }' >> /usr/local/etc/php/php.ini
 `;
 }

From cf9ad7c3eaabcdf288e51a4655de01580ed99be9 Mon Sep 17 00:00:00 2001
From: Noah Allen <noahtallen@gmail.com>
Date: Wed, 2 Dec 2020 15:54:46 -0800
Subject: [PATCH 03/15] Remove xdebug_info call

---
 lib/load.php | 1 -
 1 file changed, 1 deletion(-)

diff --git a/lib/load.php b/lib/load.php
index cc9b320667fbba..967c995ee413a8 100644
--- a/lib/load.php
+++ b/lib/load.php
@@ -5,7 +5,6 @@
  * @package gutenberg
  */
 
-// xdebug_info(); exit;
 if ( ! defined( 'ABSPATH' ) ) {
 	die( 'Silence is golden.' );
 }

From 3fa0a5faf3a777b6bd304f8a917b4bbe5fba52cd Mon Sep 17 00:00:00 2001
From: Noah Allen <noahtallen@gmail.com>
Date: Wed, 2 Dec 2020 16:05:01 -0800
Subject: [PATCH 04/15] Use correct Xdebug spelling

---
 .vscode/launch.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.vscode/launch.json b/.vscode/launch.json
index cf995dc21d1eac..17994be854c83a 100644
--- a/.vscode/launch.json
+++ b/.vscode/launch.json
@@ -5,7 +5,7 @@
 	"version": "0.2.0",
 	"configurations": [
 		{
-			"name": "Listen for XDebug",
+			"name": "Listen for Xdebug",
 			"type": "php",
 			"request": "launch",
 			"port": 9003,

From 012f659d7f68094253e7fcce26336b7049386115 Mon Sep 17 00:00:00 2001
From: Noah Allen <noahtallen@gmail.com>
Date: Mon, 7 Dec 2020 13:56:35 -0800
Subject: [PATCH 05/15] Add Xdebug mode parsing

---
 packages/env/lib/cli.js                |  7 ++++
 packages/env/lib/commands/start.js     |  5 +--
 packages/env/lib/init-config.js        | 15 ++++----
 packages/env/lib/parse-xdebug-mode.js  | 47 ++++++++++++++++++++++++++
 packages/env/test/parse-xdebug-mode.js | 34 +++++++++++++++++++
 5 files changed, 100 insertions(+), 8 deletions(-)
 create mode 100644 packages/env/lib/parse-xdebug-mode.js
 create mode 100644 packages/env/test/parse-xdebug-mode.js

diff --git a/packages/env/lib/cli.js b/packages/env/lib/cli.js
index aa94fd7c5b72dd..2ba659969fe143 100644
--- a/packages/env/lib/cli.js
+++ b/packages/env/lib/cli.js
@@ -11,6 +11,7 @@ const terminalLink = require( 'terminal-link' );
  * Internal dependencies
  */
 const env = require( './env' );
+const parseXdebugMode = require( './parse-xdebug-mode' );
 
 // Colors
 const boldWhite = chalk.bold.white;
@@ -99,6 +100,12 @@ module.exports = function cli() {
 					'Download source updates and apply WordPress configuration.',
 				default: false,
 			} );
+			args.option( 'xdebug', {
+				describe:
+					'Enables Xdebug. If not passed, Xdebug is turned off. If no modes are set, uses "debug". You may set multiple Xdebug modes by passing them in a comma-separated list: `--xdebug=develop,coverage`. See https://xdebug.org/docs/all_settings#mode for information about Xdebug modes.',
+				coerce: parseXdebugMode,
+				type: 'string',
+			} );
 		},
 		withSpinner( env.start )
 	);
diff --git a/packages/env/lib/commands/start.js b/packages/env/lib/commands/start.js
index 2ef2e0d52e70d8..2b246aba72d7a6 100644
--- a/packages/env/lib/commands/start.js
+++ b/packages/env/lib/commands/start.js
@@ -42,12 +42,13 @@ const CONFIG_CACHE_KEY = 'config_checksum';
  * @param {Object}  options.spinner A CLI spinner which indicates progress.
  * @param {boolean} options.debug   True if debug mode is enabled.
  * @param {boolean} options.update  If true, update sources.
+ * @param {string}  options.xdebug  The Xdebug mode to set.
  */
-module.exports = async function start( { spinner, debug, update } ) {
+module.exports = async function start( { spinner, debug, update, xdebug } ) {
 	spinner.text = 'Reading configuration.';
 	await checkForLegacyInstall( spinner );
 
-	const config = await initConfig( { spinner, debug } );
+	const config = await initConfig( { spinner, debug, xdebug } );
 
 	if ( ! config.detectedLocalConfig ) {
 		const { configDirectoryPath } = config;
diff --git a/packages/env/lib/init-config.js b/packages/env/lib/init-config.js
index af65dba46d0b1a..87d2f529c5bd23 100644
--- a/packages/env/lib/init-config.js
+++ b/packages/env/lib/init-config.js
@@ -23,10 +23,14 @@ const buildDockerComposeConfig = require( './build-docker-compose-config' );
  * @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".
  * @return {WPConfig} The-env config object.
  */
-module.exports = async function initConfig( { spinner, debug } ) {
+module.exports = async function initConfig( {
+	spinner,
+	debug,
+	xdebug = 'off',
+} ) {
 	const configPath = path.resolve( '.wp-env.json' );
 	const config = await readConfig( configPath );
 	config.debug = debug;
@@ -39,12 +43,11 @@ module.exports = async function initConfig( { spinner, debug } ) {
 		yaml.dump( dockerComposeConfig )
 	);
 
-	const XdebugMode = 'debug';
 	await fs.writeFile(
 		path.resolve( config.workDirectoryPath, 'Dockerfile' ),
 		dockerFileContents(
 			dockerComposeConfig.services.wordpress.image,
-			XdebugMode
+			xdebug
 		)
 	);
 
@@ -66,7 +69,7 @@ module.exports = async function initConfig( { spinner, debug } ) {
 	return config;
 };
 
-function dockerFileContents( image, XdebugMode ) {
+function dockerFileContents( image, xdebugMode ) {
 	const isLinux = os.type() === 'Linux';
 	// Discover client host does not appear to work on macOS with Docker.
 	const clientDetectSettings = isLinux
@@ -81,7 +84,7 @@ RUN apt -qy install $PHPIZE_DEPS \\
 
 RUN touch /usr/local/etc/php/php.ini
 RUN echo 'xdebug.start_with_request=yes' >> /usr/local/etc/php/php.ini
-RUN echo 'xdebug.mode=${ XdebugMode }' >> /usr/local/etc/php/php.ini
+RUN echo 'xdebug.mode=${ xdebugMode }' >> /usr/local/etc/php/php.ini
 RUN echo '${ clientDetectSettings }' >> /usr/local/etc/php/php.ini
 `;
 }
diff --git a/packages/env/lib/parse-xdebug-mode.js b/packages/env/lib/parse-xdebug-mode.js
new file mode 100644
index 00000000000000..2be7c8a5be5cd3
--- /dev/null
+++ b/packages/env/lib/parse-xdebug-mode.js
@@ -0,0 +1,47 @@
+// See https://xdebug.org/docs/all_settings#mode
+const XDEBUG_MODES = [
+	'develop',
+	'coverage',
+	'debug',
+	'gcstats',
+	'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.
+ *
+ * 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
+ * @return {string} The Xdebug mode to use with defaults applied.
+ */
+module.exports = function parseXdebugMode( value ) {
+	if ( typeof value !== 'string' ) {
+		throwXdebugModeError( value );
+	}
+
+	if ( value.length === 0 ) {
+		return 'debug';
+	}
+
+	const modes = value.split( ',' );
+	modes.forEach( ( userMode ) => {
+		if ( ! XDEBUG_MODES.some( ( realMode ) => realMode === userMode ) ) {
+			throwXdebugModeError( userMode );
+		}
+	} );
+	return value;
+};
+
+function throwXdebugModeError( value ) {
+	throw new Error(
+		`"${ value }" is not a mode recognized by Xdebug. Valid modes are: ${ XDEBUG_MODES.join(
+			', '
+		) }`
+	);
+}
diff --git a/packages/env/test/parse-xdebug-mode.js b/packages/env/test/parse-xdebug-mode.js
new file mode 100644
index 00000000000000..532fc6b6daae8a
--- /dev/null
+++ b/packages/env/test/parse-xdebug-mode.js
@@ -0,0 +1,34 @@
+/**
+ * Internal dependencies
+ */
+const parseXdebugMode = require( '../lib/parse-xdebug-mode' );
+
+describe( 'parseXdebugMode', () => {
+	it( 'throws an error if the passed value is not a string', () => {
+		expect( () => parseXdebugMode() ).toThrow(
+			'is not a mode recognized by Xdebug'
+		);
+	} );
+
+	it( 'sets the Xdebug mode to "debug" if no mode is specified', () => {
+		const result = parseXdebugMode( '' );
+		expect( result ).toEqual( 'debug' );
+	} );
+
+	it( 'throws an error if a given mode is not recognized, including the invalid mode in the output', () => {
+		const fakeMode = 'fake-mode-123';
+		expect.assertions( 2 );
+		// Single mode:
+		expect( () => parseXdebugMode( fakeMode ) ).toThrow( fakeMode );
+
+		// Many modes:
+		expect( () =>
+			parseXdebugMode( `debug,profile,${ fakeMode }` )
+		).toThrow( fakeMode );
+	} );
+
+	it( 'returns all modes passed', () => {
+		const result = parseXdebugMode( 'debug,profile,trace' );
+		expect( result ).toEqual( 'debug,profile,trace' );
+	} );
+} );

From 33ef398e2c28cf4dea7073200dc83727e5271f63 Mon Sep 17 00:00:00 2001
From: Noah Allen <noahtallen@gmail.com>
Date: Tue, 8 Dec 2020 16:16:59 -0800
Subject: [PATCH 06/15] Only write docker changes on wp-env start

---
 packages/env/lib/commands/start.js |  7 +++-
 packages/env/lib/init-config.js    | 58 ++++++++++++++++++++----------
 2 files changed, 46 insertions(+), 19 deletions(-)

diff --git a/packages/env/lib/commands/start.js b/packages/env/lib/commands/start.js
index 2b246aba72d7a6..0d2b2b717b0053 100644
--- a/packages/env/lib/commands/start.js
+++ b/packages/env/lib/commands/start.js
@@ -48,7 +48,12 @@ module.exports = async function start( { spinner, debug, update, xdebug } ) {
 	spinner.text = 'Reading configuration.';
 	await checkForLegacyInstall( spinner );
 
-	const config = await initConfig( { spinner, debug, xdebug } );
+	const config = await initConfig( {
+		spinner,
+		debug,
+		xdebug,
+		writeChanges: true,
+	} );
 
 	if ( ! config.detectedLocalConfig ) {
 		const { configDirectoryPath } = config;
diff --git a/packages/env/lib/init-config.js b/packages/env/lib/init-config.js
index 87d2f529c5bd23..755b57d5fa1111 100644
--- a/packages/env/lib/init-config.js
+++ b/packages/env/lib/init-config.js
@@ -2,7 +2,8 @@
  * External dependencies
  */
 const path = require( 'path' );
-const fs = require( 'fs' ).promises;
+const { writeFile, mkdir } = require( 'fs' ).promises;
+const { existsSync } = require( 'fs' );
 const yaml = require( 'js-yaml' );
 const os = require( 'os' );
 
@@ -21,35 +22,27 @@ const buildDockerComposeConfig = require( './build-docker-compose-config' );
  * ./.wp-env.json, creates ~/.wp-env, and creates ~/.wp-env/docker-compose.yml.
  *
  * @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 {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 {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.
  * @return {WPConfig} The-env config object.
  */
 module.exports = async function initConfig( {
 	spinner,
 	debug,
 	xdebug = 'off',
+	writeChanges = false,
 } ) {
 	const configPath = path.resolve( '.wp-env.json' );
 	const config = await readConfig( configPath );
 	config.debug = debug;
 
-	await fs.mkdir( config.workDirectoryPath, { recursive: true } );
-
 	const dockerComposeConfig = buildDockerComposeConfig( config );
-	await fs.writeFile(
-		config.dockerComposeConfigPath,
-		yaml.dump( dockerComposeConfig )
-	);
-
-	await fs.writeFile(
-		path.resolve( config.workDirectoryPath, 'Dockerfile' ),
-		dockerFileContents(
-			dockerComposeConfig.services.wordpress.image,
-			xdebug
-		)
-	);
 
 	if ( config.debug ) {
 		spinner.info(
@@ -66,6 +59,35 @@ module.exports = async function initConfig( {
 		spinner.start();
 	}
 
+	/**
+	 * We avoid writing changes most of the time so that we can better pass params
+	 * to the start command. For example, say you start wp-env with Xdebug enabled.
+	 * If you then run another command, like opening bash in the wp instance, it
+	 * would turn off Xdebug in the Dockerfile because it wouldn't have the --xdebug
+	 * arg. This basically makes it such that wp-env start is the only command
+	 * which updates any of the Docker configuration.
+	 */
+	if ( writeChanges ) {
+		await mkdir( config.workDirectoryPath, { recursive: true } );
+
+		await writeFile(
+			config.dockerComposeConfigPath,
+			yaml.dump( dockerComposeConfig )
+		);
+
+		await writeFile(
+			path.resolve( config.workDirectoryPath, 'Dockerfile' ),
+			dockerFileContents(
+				dockerComposeConfig.services.wordpress.image,
+				xdebug
+			)
+		);
+	} else if ( ! existsSync( config.workDirectoryPath ) ) {
+		throw new Error(
+			'wp-env has not yet been initalized. Please run `wp-env start` to initalize the WordPress instance before using any other commands.'
+		);
+	}
+
 	return config;
 };
 

From da48079da3ee39252835a595be07dcd246732217 Mon Sep 17 00:00:00 2001
From: Noah Allen <noahtallen@gmail.com>
Date: Tue, 8 Dec 2020 16:22:42 -0800
Subject: [PATCH 07/15] Improve error handling

---
 packages/env/lib/init-config.js | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/packages/env/lib/init-config.js b/packages/env/lib/init-config.js
index 755b57d5fa1111..8e262021fb8afc 100644
--- a/packages/env/lib/init-config.js
+++ b/packages/env/lib/init-config.js
@@ -83,9 +83,10 @@ module.exports = async function initConfig( {
 			)
 		);
 	} else if ( ! existsSync( config.workDirectoryPath ) ) {
-		throw new Error(
+		spinner.fail(
 			'wp-env has not yet been initalized. Please run `wp-env start` to initalize the WordPress instance before using any other commands.'
 		);
+		process.exit( 1 );
 	}
 
 	return config;

From 3269bdd5ee7b1ef56ad28129d0e5d202eb078ff5 Mon Sep 17 00:00:00 2001
From: Noah Allen <noahtallen@gmail.com>
Date: Tue, 8 Dec 2020 16:28:44 -0800
Subject: [PATCH 08/15] More verbose error message

---
 packages/env/lib/init-config.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/env/lib/init-config.js b/packages/env/lib/init-config.js
index 8e262021fb8afc..3364cd042af285 100644
--- a/packages/env/lib/init-config.js
+++ b/packages/env/lib/init-config.js
@@ -84,7 +84,7 @@ module.exports = async function initConfig( {
 		);
 	} else if ( ! existsSync( config.workDirectoryPath ) ) {
 		spinner.fail(
-			'wp-env has not yet been initalized. Please run `wp-env start` to initalize the WordPress instance before using any other commands.'
+			'wp-env has not yet been initalized. Please run `wp-env start` to install the WordPress instance before using any other commands. This is only necessary to set up the environment for the first time; it is typically not necessary for the instance to be running after that in order to use other commands.'
 		);
 		process.exit( 1 );
 	}

From 85cde080f1e0ba4e004ee02294cf7ce180b3d482 Mon Sep 17 00:00:00 2001
From: Noah Allen <noahtallen@gmail.com>
Date: Tue, 8 Dec 2020 16:40:20 -0800
Subject: [PATCH 09/15] Update changelog

---
 packages/env/CHANGELOG.md | 13 ++++++++++++-
 1 file changed, 12 insertions(+), 1 deletion(-)

diff --git a/packages/env/CHANGELOG.md b/packages/env/CHANGELOG.md
index 093b73e90686b9..7b6f35b079a1f5 100644
--- a/packages/env/CHANGELOG.md
+++ b/packages/env/CHANGELOG.md
@@ -2,9 +2,20 @@
 
 ## Unreleased
 
+### Breaking Changes
+
+-   `wp-env start` is now the only command which writes to the docker configuration files. Previously, running any command would also parse the config and then write it to the correct location. Now, other commands still parse the config, but they will not overwrite the confugiration which was set by wp-env start. This allows parameters to be passed to wp-env start which can affect the configuration.
+
 ### Enhancement
 
-- Update nodegit dependency to 0.27.0, the earlier version does not have pre-built binaries for Node 14.15.0 LTS. Upgrading provides support without requiring building nodegit locally.
+-   Update nodegit dependency to 0.27.0, the earlier version does not have pre-built binaries for Node 14.15.0 LTS. Upgrading provides support without requiring building nodegit locally.
+-   Allow WP_HOME wp-config value to be set to a custom port other than the default for the docker instance.
+-   Append the instance URL to output of `wp-env start`.
+
+### New feature
+
+-   Add support for setting the PHP version used for the WordPress instance via wp-env.json.
+-   Add Xdebug 3 to the development environment. You can enable Xdebug with `wp-env start --xdebug` (for debug mode) or `wp-env start --xdebug=develop,coverage` for custom modes.
 
 ## 2.0.0 (2020-09-03)
 

From 4109fd6a50e8beaed29cb0e953c12ea172b49678 Mon Sep 17 00:00:00 2001
From: Noah Allen <noahtallen@gmail.com>
Date: Tue, 8 Dec 2020 16:43:28 -0800
Subject: [PATCH 10/15] Remove launch.json

---
 .vscode/launch.json | 17 -----------------
 1 file changed, 17 deletions(-)
 delete mode 100644 .vscode/launch.json

diff --git a/.vscode/launch.json b/.vscode/launch.json
deleted file mode 100644
index 17994be854c83a..00000000000000
--- a/.vscode/launch.json
+++ /dev/null
@@ -1,17 +0,0 @@
-{
-	// Use IntelliSense to learn about possible attributes.
-	// Hover to view descriptions of existing attributes.
-	// For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
-	"version": "0.2.0",
-	"configurations": [
-		{
-			"name": "Listen for Xdebug",
-			"type": "php",
-			"request": "launch",
-			"port": 9003,
-			"pathMappings": {
-				"/var/www/html/wp-content/plugins/gutenberg": "${workspaceRoot}/"
-			}
-		}
-	]
-}
\ No newline at end of file

From c4c3b3d8fb01adf48fe79093ca33dfed1fecc6c3 Mon Sep 17 00:00:00 2001
From: Noah Allen <noahtallen@gmail.com>
Date: Tue, 8 Dec 2020 16:55:23 -0800
Subject: [PATCH 11/15] Update changelog again

---
 packages/env/CHANGELOG.md | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/packages/env/CHANGELOG.md b/packages/env/CHANGELOG.md
index 7b6f35b079a1f5..3bf6a54396b951 100644
--- a/packages/env/CHANGELOG.md
+++ b/packages/env/CHANGELOG.md
@@ -14,9 +14,13 @@
 
 ### New feature
 
--   Add support for setting the PHP version used for the WordPress instance via wp-env.json.
+-   Add support for setting the PHP version used for the WordPress instance. For example, test PHP 8 with `"phpVersion": 8.0` in wp-env.json.
 -   Add Xdebug 3 to the development environment. You can enable Xdebug with `wp-env start --xdebug` (for debug mode) or `wp-env start --xdebug=develop,coverage` for custom modes.
 
+### Bug Fixes
+
+-   ZIP-based plugin sources are now downloaded to a directory using the basename of the URL instead of the full URL path. This prevents HTML encoded characters in the URL (like "/") from being improperly encoded into the filesystem. This fixes the issue where many .zip sources broke because files with these badly formatted characters were not loaded as assets.
+
 ## 2.0.0 (2020-09-03)
 
 ### Breaking Changes

From dad241ab26ff3e4f3ba9857e8a0131168e070e35 Mon Sep 17 00:00:00 2001
From: Noah Allen <noahtallen@gmail.com>
Date: Tue, 8 Dec 2020 17:02:22 -0800
Subject: [PATCH 12/15] Make sure config is different when xdebug param changes

---
 packages/env/lib/init-config.js | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/packages/env/lib/init-config.js b/packages/env/lib/init-config.js
index 3364cd042af285..6f9ddb116d41a4 100644
--- a/packages/env/lib/init-config.js
+++ b/packages/env/lib/init-config.js
@@ -42,6 +42,11 @@ module.exports = async function initConfig( {
 	const config = await readConfig( configPath );
 	config.debug = debug;
 
+	// Adding these to the config allows the start config to understand that the
+	// config has changed when only the xdebug param has changed. This is needed
+	// so that Docker will rebuild the image whenever the xdebug flag changes.
+	config.xdebug = xdebug;
+
 	const dockerComposeConfig = buildDockerComposeConfig( config );
 
 	if ( config.debug ) {

From d62cdb67672f8cee9471d4031e4ac53c1623d47b Mon Sep 17 00:00:00 2001
From: Noah Allen <noahtallen@gmail.com>
Date: Tue, 8 Dec 2020 17:03:55 -0800
Subject: [PATCH 13/15] Fix typo

---
 packages/env/lib/init-config.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/env/lib/init-config.js b/packages/env/lib/init-config.js
index 6f9ddb116d41a4..68e16781d94e9e 100644
--- a/packages/env/lib/init-config.js
+++ b/packages/env/lib/init-config.js
@@ -42,7 +42,7 @@ module.exports = async function initConfig( {
 	const config = await readConfig( configPath );
 	config.debug = debug;
 
-	// Adding these to the config allows the start config to understand that the
+	// Adding this to the config allows the start command to understand that the
 	// config has changed when only the xdebug param has changed. This is needed
 	// so that Docker will rebuild the image whenever the xdebug flag changes.
 	config.xdebug = xdebug;

From 6f9ad25fa0427d87454d39b70a342925c3146165 Mon Sep 17 00:00:00 2001
From: Noah Allen <noahtallen@gmail.com>
Date: Tue, 8 Dec 2020 17:22:08 -0800
Subject: [PATCH 14/15] Add Xdebug documentation

---
 packages/env/README.md | 57 ++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 55 insertions(+), 2 deletions(-)

diff --git a/packages/env/README.md b/packages/env/README.md
index 78f94c73c5a7ea..d5667f6753a147 100644
--- a/packages/env/README.md
+++ b/packages/env/README.md
@@ -188,6 +188,51 @@ wp-env start --debug
 	...
 ```
 
+## Using Xdebug
+
+Xdebug is installed in the wp-env environment, but it is turned off by default. To enable Xdebug, you can use the `--xdebug` flag with the `wp-env start` command. Here is a reference to how the flag works:
+
+```sh
+# Sets the Xdebug mode to "debug" (for step debugging):
+wp-env start --xdebug
+
+# Sets the Xdebug mode to "off":
+wp-env start
+
+# Enables each of the Xdebug modes listed:
+wp-env start --xdebug=profile,trace,debug
+```
+
+You can see a reference on each of the Xdebug modes and what they do in the [Xdebug documentation](https://xdebug.org/docs/all_settings#mode).
+
+### Xdebug IDE support
+
+To connect to Xdebug from your IDE, you can use these IDE settings. This bit of JSON was tested for VS Code's `launch.json` format (which you can [learn more about here](https://code.visualstudio.com/docs/editor/debugging#_launchjson-attributes)) along with [this PHP Debug extension](https://marketplace.visualstudio.com/items?itemName=felixfbecker.php-debug). Its path mapping also points to a specific plugin -- you should update this to point to the source you are working with inside of the wp-env instance.
+
+You should only have to translate `port` and `pathMappings` to the format used by your own IDE.
+
+```json
+{
+	"name": "Listen for XDebug",
+	"type": "php",
+	"request": "launch",
+	"port": 9003,
+	"pathMappings": {
+		"/var/www/html/wp-content/plugins/gutenberg": "${workspaceRoot}/"
+	}
+}
+```
+
+Once your IDEs Xdebug settings have been enabled, you should just have to launch the debugger, put a breakpoint on any line of PHP code, and then refresh your browser!
+
+Here is a summary:
+
+1. Start wp-env with xdebug enabled: `wp-env start --xdebug`
+2. Install a suitable Xdebug extension for your IDE if it does not include one already.
+3. Configure the IDE debugger to use port `9003` and the correct source files in wp-env.
+4. Launch the debugger and put a breakpoint on any line of PHP code.
+5. Refresh the URL wp-env is running at and the breakpoint should trigger.
+
 ## Command reference
 
 `wp-env` creates generated files in the `wp-env` home directory. By default, this is `~/.wp-env`. The exception is Linux, where files are placed at `~/wp-env` [for compatibility with Snap Packages](https://github.com/WordPress/gutenberg/issues/20180#issuecomment-587046325). The `wp-env` home directory contains a subdirectory for each project named `/$md5_of_project_path`. To change the `wp-env` home directory, set the `WP_ENV_HOME` environment variable. For example, running `WP_ENV_HOME="something" wp-env start` will download the project files to the directory `./something/$md5_of_project_path` (relative to the current directory).
@@ -202,12 +247,20 @@ 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.
+.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]
+  --xdebug   Enables Xdebug. If not passed, Xdebug is turned off. If no modes
+             are set, uses "debug". You may set multiple Xdebug modes by passing
+             them in a comma-separated list: `--xdebug=develop,coverage`. See
+             https://xdebug.org/docs/all_settings#mode for information about
+             Xdebug modes.                                              [string]
 ```
 
 ### `wp-env stop`

From 8de5ae8d7a7c6ee73a88e29d53b7af4711f438c6 Mon Sep 17 00:00:00 2001
From: Noah Allen <noahtallen@gmail.com>
Date: Tue, 8 Dec 2020 17:41:31 -0800
Subject: [PATCH 15/15] Add launch.json config for Xdebug

---
 .vscode/launch.json | 14 ++++++++++++++
 1 file changed, 14 insertions(+)
 create mode 100644 .vscode/launch.json

diff --git a/.vscode/launch.json b/.vscode/launch.json
new file mode 100644
index 00000000000000..3e333f450a0013
--- /dev/null
+++ b/.vscode/launch.json
@@ -0,0 +1,14 @@
+{
+	"version": "0.2.0",
+	"configurations": [
+		{
+			"name": "Listen for Xdebug",
+			"type": "php",
+			"request": "launch",
+			"port": 9003,
+			"pathMappings": {
+				"/var/www/html/wp-content/plugins/gutenberg": "${workspaceRoot}/"
+			}
+		}
+	]
+}
\ No newline at end of file