@wordpress/env 4.2.1 → 4.3.0-next.e230fbab09.0

package/README.md

@@ -51,7 +51,7 @@ Then modify your package.json and add an extra command to npm `scripts` (https:/
 When installing `wp-env` in this way, all `wp-env` commands detailed in these docs must be prefixed with `npm run`, for example:
 
 ```sh
-# You must add another dash to pass the "update" flag to wp-env
+# You must add another double dash to pass the "update" flag to wp-env
 $ npm run wp-env start -- --update
 ```
 
@@ -203,6 +203,14 @@ wp-env start
 wp-env start --xdebug=profile,trace,debug
 ```
 
+When you're running `wp-env` using `npm run`, like when working in the Gutenberg repo or when having `wp-env` as a local project dependency, don't forget to add an extra double dash before the `--xdebug` command:
+
+```sh
+npm run wp-env start -- --xdebug
+```
+
+If you forget about that, the `--xdebug` parameter will be passed to NPM instead of the `wp-env start` command and it will be ignored.
+
 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).
 
 _Since we are only installing Xdebug 3, Xdebug is only supported for PHP versions greater than or equal to 7.2 (the default). Xdebug won't be installed if `phpVersion` is set to a legacy version._
@@ -215,16 +223,18 @@ You should only have to translate `port` and `pathMappings` to the format used b
 
 ```json
 {
-	"name": "Listen for XDebug",
-	"type": "php",
-	"request": "launch",
-	"port": 9003,
-	"pathMappings": {
-		"/var/www/html/wp-content/plugins/gutenberg": "${workspaceFolder}/"
-	}
+  "name": "Listen for XDebug",
+  "type": "php",
+  "request": "launch",
+  "port": 9003,
+  "pathMappings": {
+    "/var/www/html/wp-content/plugins/gutenberg": "${workspaceFolder}/"
+  }
 }
 ```
 
+After you create a `.vscode/launch.json` file in your repository, you probably want to add it to your [global gitignore file](https://docs.github.com/en/get-started/getting-started-with-git/ignoring-files#configuring-ignored-files-for-all-repositories-on-your-computer) so that it stays private for you and is not committed to the repository.
+
 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:
@@ -287,6 +297,24 @@ Positionals:
 
 ### `wp-env run [container] [command]`
 
+The run command can be used to open shell sessions or invoke WP-CLI commands.
+
+<div class="callout callout-alert">
+To run a WP-CLI command that includes optional arguments, enclose the WP-CLI command in quotation marks; otherwise, the optional arguments are ignored. This is because flags are normally passed to `wp-env` itself, meaning that the flags are not considered part of the argument that specifies the WP-CLI command. With quotation marks, `wp-env` considers everything inside quotation marks the WP-CLI command argument.
+
+For example, to list cron schedules with optional arguments that specify the fields returned and the format of the output:
+
+```sh
+wp-env run cli "wp cron schedule list --fields=name --format=csv"
+```
+
+Without the quotation marks, WP-CLI lists the schedule in its default format, ignoring the `fields` and `format` arguments.
+</div>
+
+Note that quotation marks are not required for a WP-CLI command that excludes optional arguments, although it does not hurt to include them. For example, the following command syntaxes return identical results: `wp-env run cli "wp cron schedule list"` or `wp-env run cli wp cron schedule list`.
+
+For more information about all the available commands, see [WP-CLI Commands](https://developer.wordpress.org/cli/commands/).
+
 ```sh
 wp-env run <container> [command..]
 
@@ -353,7 +381,7 @@ wp> ^C
 #### Installing a plugin or theme on the development instance
 
 ```sh
-wp-env run cli plugin install custom-post-type-ui
+wp-env run cli wp plugin install custom-post-type-ui
 
 Creating 500cd328b649d63e882d5c4695871d04_cli_run ... done
 Installing Custom Post Type UI (1.9.2)
@@ -445,22 +473,22 @@ Additionally, the key `env` is available to override any of the above options on
 
 ```json
 {
-	"plugins": [ "." ],
-	"config": {
-		"KEY_1": true,
-		"KEY_2": false
-	},
-	"env": {
-		"development": {
-			"themes": [ "./one-theme" ]
-		},
-		"tests": {
-			"config": {
-				"KEY_1": false
-			},
-			"port": 3000
-		}
-	}
+  "plugins": ["."],
+  "config": {
+    "KEY_1": true,
+    "KEY_2": false
+  },
+  "env": {
+    "development": {
+      "themes": ["./one-theme"]
+    },
+    "tests": {
+      "config": {
+        "KEY_1": false
+      },
+      "port": 3000
+    }
+  }
 }
 ```
 
@@ -501,8 +529,8 @@ This is useful for plugin development.
 
 ```json
 {
-	"core": null,
-	"plugins": [ "." ]
+  "core": null,
+  "plugins": ["."]
 }
 ```
 
@@ -512,8 +540,8 @@ This is useful for plugin development when upstream Core changes need to be test
 
 ```json
 {
-	"core": "WordPress/WordPress#master",
-	"plugins": [ "." ]
+  "core": "WordPress/WordPress#master",
+  "plugins": ["."]
 }
 ```
 
@@ -525,8 +553,8 @@ If you are running a _build_ of `wordpress-develop`, point `core` to the `build`
 
 ```json
 {
-	"core": "../wordpress-develop/build",
-	"plugins": [ "." ]
+  "core": "../wordpress-develop/build",
+  "plugins": ["."]
 }
 ```
 
@@ -534,8 +562,8 @@ If you are running `wordpress-develop` in a dev mode (e.g. the watch command `de
 
 ```json
 {
-	"core": "../wordpress-develop/src",
-	"plugins": [ "." ]
+  "core": "../wordpress-develop/src",
+  "plugins": ["."]
 }
 ```
 
@@ -545,9 +573,9 @@ This is useful for integration testing: that is, testing how old versions of Wor
 
 ```json
 {
-	"core": "WordPress/WordPress#5.2.0",
-	"plugins": [ "WordPress/wp-lazy-loading", "WordPress/classic-editor" ],
-	"themes": [ "WordPress/theme-experiments" ]
+  "core": "WordPress/WordPress#5.2.0",
+  "plugins": ["WordPress/wp-lazy-loading", "WordPress/classic-editor"],
+  "themes": ["WordPress/theme-experiments"]
 }
 ```
 
@@ -557,12 +585,12 @@ You can add mu-plugins via the mapping config. The mapping config also allows yo
 
 ```json
 {
-	"plugins": [ "." ],
-	"mappings": {
-		"wp-content/mu-plugins": "./path/to/local/mu-plugins",
-		"wp-content/themes": "./path/to/local/themes",
-		"wp-content/themes/specific-theme": "./path/to/local/theme-1"
-	}
+  "plugins": ["."],
+  "mappings": {
+    "wp-content/mu-plugins": "./path/to/local/mu-plugins",
+    "wp-content/themes": "./path/to/local/themes",
+    "wp-content/themes/specific-theme": "./path/to/local/theme-1"
+  }
 }
 ```
 
@@ -572,10 +600,10 @@ Since all plugins in the `plugins` key are activated by default, you should use
 
 ```json
 {
-	"plugins": [ "." ],
-	"mappings": {
-		"wp-content/plugins/my-test-plugin": "./path/to/test/plugin"
-	}
+  "plugins": ["."],
+  "mappings": {
+    "wp-content/plugins/my-test-plugin": "./path/to/test/plugin"
+  }
 }
 ```
 
@@ -585,12 +613,12 @@ If you need a plugin active in one environment but not the other, you can use `e
 
 ```json
 {
-	"plugins": [ "." ],
-	"env": {
-		"tests": {
-			"plugins": [ ".", "path/to/test/plugin" ]
-		}
-	}
+  "plugins": ["."],
+  "env": {
+    "tests": {
+      "plugins": [".", "path/to/test/plugin"]
+    }
+  }
 }
 ```
 
@@ -600,13 +628,13 @@ You can tell `wp-env` to use a custom port number so that your instance does not
 
 ```json
 {
-	"plugins": [ "." ],
-	"port": 4013,
-	"env": {
-		"tests": {
-			"port": 4012
-		}
-	}
+  "plugins": ["."],
+  "port": 4013,
+  "env": {
+    "tests": {
+      "port": 4012
+    }
+  }
 }
 ```
 
@@ -616,8 +644,8 @@ You can tell `wp-env` to use a specific PHP version for compatibility and testin
 
 ```json
 {
-	"phpVersion": "7.2",
-	"plugins": [ "." ]
+  "phpVersion": "7.2",
+  "plugins": ["."]
 }
 ```
 

package/lib/cli.js

@@ -14,14 +14,14 @@ const { execSync } = require( 'child_process' );
 const env = require( './env' );
 const parseXdebugMode = require( './parse-xdebug-mode' );
 
-// Colors
+// Colors.
 const boldWhite = chalk.bold.white;
 const wpPrimary = boldWhite.bgHex( '#00669b' );
 const wpGreen = boldWhite.bgHex( '#4ab866' );
 const wpRed = boldWhite.bgHex( '#d94f4f' );
 const wpYellow = boldWhite.bgHex( '#f0b849' );
 
-// Spinner
+// Spinner.
 const withSpinner = ( command ) => ( ...args ) => {
 	const spinner = ora().start();
 	args[ 0 ].spinner = spinner;

package/lib/config/db-env.js

@@ -1,17 +1,17 @@
-// Username and password used in all databases
+// Username and password used in all databases.
 const credentials = {
 	WORDPRESS_DB_USER: 'root',
 	WORDPRESS_DB_PASSWORD: 'password',
 };
 
-// Environment for test database
+// Environment for test database.
 const tests = {
 	WORDPRESS_DB_NAME: 'tests-wordpress',
 	WORDPRESS_DB_HOST: 'tests-mysql',
 };
 
 // Environment for development database. DB host gets default value which is set
-// elsewhere
+// elsewhere.
 const development = {
 	WORDPRESS_DB_NAME: 'wordpress',
 };

package/lib/init-config.js

@@ -111,7 +111,7 @@ function checkXdebugPhpCompatibility( config ) {
 	const phpCompatibility = true;
 
 	// If PHP version is defined
-	// ensure it meets the Xdebug minimum compatibility requirment
+	// 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 ] );
@@ -124,7 +124,7 @@ function checkXdebugPhpCompatibility( config ) {
 		}
 
 		// Xdebug 3 supports 7.2 and higher
-		// Ensure user has specified a compatible PHP version
+		// 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.' );
 		}
@@ -142,7 +142,7 @@ function checkXdebugPhpCompatibility( config ) {
  * @return {string} The dockerfile contents.
  */
 function dockerFileContents( image, config ) {
-	// Don't install XDebug unless it is explicitly required
+	// Don't install XDebug unless it is explicitly required.
 	let shouldInstallXdebug = false;
 
 	if ( config.xdebug !== 'off' ) {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wordpress/env",
-	"version": "4.2.1",
+	"version": "4.3.0-next.e230fbab09.0",
 	"description": "A zero-config, self contained local WordPress environment for development and testing.",
 	"author": "The WordPress Contributors",
 	"license": "GPL-2.0-or-later",
@@ -51,5 +51,5 @@
 	"scripts": {
 		"test": "echo \"Error: run tests from root\" && exit 1"
 	},
-	"gitHead": "2e4922861e49f5a090f9dc52056165092cfba163"
+	"gitHead": "308df03e6a96ded732f9c4e32471b1b4f8dea54a"
 }