wp-env: Add custom port numbers to .wp-env.json

packages/env/README.md

@@ -79,6 +79,8 @@ $ WP_ENV_PORT=3333 wp-env start
 
 Running `docker ps` and inspecting the `PORTS` column allows you to determine which port `wp-env` is currently using.
 
+You may also specify the port numbers in your `.wp-env.json` file, but the environment variables take precedent.
+
 ### 3. Restart `wp-env`
 
 Restarting `wp-env` will restart the underlying Docker containers which can fix many issues.
@@ -175,15 +177,19 @@ Positionals:
 
 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.
 
-`.wp-env.json` supports three fields:
+`.wp-env.json` supports five fields:
 
 | Field | Type | Default | Description |
 | -- | -- | -- | -- |
 | `"core"` | `string|null` | `null` | The WordPress installation to use. If `null` is specified, `wp-env` will use the latest production release of WordPress. |
 | `"plugins"` | `string[]` | `[]` | A list of plugins to install and activate in the environment. |
 | `"themes"` | `string[]` | `[]` | A list of themes to install in the environment. The first theme in the list will be activated. |
+| `"portNumber"` | `string` | `"8888"` | The primary port number to use for the insallation. You'll access the instance through the port: 'http://localhost:8888'. |
+| `"testsPortNumber"` | `string` | `"8889"` | The port number to use for the tests instance. |
+
+_Note: the port number environment variables (`WP_ENV_PORT` and `WP_ENV_TESTS_PORT`) take precedent over the .wp-env.json values._
 
-Several types of strings can be passed into these fields:
+Several types of strings can be passed into the `core`, `plugins`, and `themes` fields:
 
 | Type | Format | Example(s) |
 | -- | -- | -- |
@@ -251,4 +257,18 @@ This is useful for integration testing: that is, testing how old versions of Wor
 }
 ```
 
+#### Custom Port Numbers
+
+A custom port number so that your installation ports do not conflict with other wp-env instances.
+
+```json
+{
+  "plugins": [
+    ".",
+  ],
+  "portNumber": 4013,
+  "testsPortNumber": 4012
+}
+```
+
 <br/><br/><p align="center"><img src="https://s.w.org/style/images/codeispoetry.png?1" alt="Code is Poetry." /></p>

packages/env/lib/build-docker-compose-config.js

@@ -51,6 +51,10 @@ module.exports = function buildDockerComposeConfig( config ) {
 		...themeMounts,
 	];
 
+	// Set the default ports based on the config values.
+	const mainPort = `\${WP_ENV_PORT:-${ config.portNumber }}:80`;
+	const testsPort = `\${WP_ENV_TESTS_PORT:-${ config.testsPortNumber }}:80`;
+
 	return {
 		version: '3.7',
 		services: {
@@ -63,7 +67,7 @@ module.exports = function buildDockerComposeConfig( config ) {
 			wordpress: {
 				depends_on: [ 'mysql' ],
 				image: 'wordpress',
-				ports: [ '${WP_ENV_PORT:-8888}:80' ],
+				ports: [ mainPort ],
 				environment: {
 					WORDPRESS_DEBUG: '1',
 					WORDPRESS_DB_NAME: 'wordpress',
@@ -73,7 +77,7 @@ module.exports = function buildDockerComposeConfig( config ) {
 			'tests-wordpress': {
 				depends_on: [ 'mysql' ],
 				image: 'wordpress',
-				ports: [ '${WP_ENV_TESTS_PORT:-8889}:80' ],
+				ports: [ testsPort ],
 				environment: {
 					WORDPRESS_DEBUG: '1',
 					WORDPRESS_DB_NAME: 'tests-wordpress',

packages/env/lib/config.js

@@ -35,6 +35,8 @@ const HOME_PATH_PREFIX = `~${ path.sep }`;
  * @property {Source|null} coreSource The WordPress installation to load in the environment.
  * @property {Source[]} pluginSources Plugins to load in the environment.
  * @property {Source[]} themeSources Themes to load in the environment.
+ * @property {number} portNumber The port on which to start the main WordPress environment.
+ * @property {number} testsPortNumber The port on which to start the tests WordPress environment.
  */
 
 /**
@@ -96,6 +98,8 @@ module.exports = {
 				core: null,
 				plugins: [],
 				themes: [],
+				portNumber: 8888,
+				testsPortNumber: 8889,
 			},
 			config
 		);
@@ -124,6 +128,24 @@ module.exports = {
 			);
 		}
 
+		if ( ! Number.isInteger( config.portNumber ) ) {
+			throw new ValidationError(
+				'Invalid .wp-env.json: "portNumber" must be an integer.'
+			);
+		}
+
+		if ( ! Number.isInteger( config.testsPortNumber ) ) {
+			throw new ValidationError(
+				'Invalid .wp-env.json: "testsPortNumber" must be an integer.'
+			);
+		}
+
+		if ( config.testsPortNumber === config.portNumber ) {
+			throw new ValidationError(
+				'Invalid .wp-env.json: "testsPortNumber" and "portNumber" must be different.'
+			);
+		}
+
 		const workDirectoryPath = path.resolve(
 			os.homedir(),
 			'.wp-env',
@@ -134,6 +156,8 @@ module.exports = {
 			name: path.basename( configDirectoryPath ),
 			configDirectoryPath,
 			workDirectoryPath,
+			portNumber: config.portNumber,
+			testsPortNumber: config.testsPortNumber,
 			dockerComposeConfigPath: path.resolve(
 				workDirectoryPath,
 				'docker-compose.yml'