- Remove
versionfield from docker-compose config generated by env package #63099. Docker has starting throwing a warning that this property is obsolete and should be removed.
- Ignore
$schemakey in environment config parsing (#62626).
- Increase the minimum required Node.js version to v18.12.0 matching long-term support releases (#31270). Learn more about Node.js releases.
- Fix
mariadbversion to LTS #59237
- Update Docker usage to
docker composeV2 following deprecation ofdocker-composeV1.
wp-envnow works offline after the environment has been created. Note that manywp-envconfiguration changes involve internet connectivity and may not work in offline mode. #53547
- Corrected
PATHto include the host user's Composer bin directory. - Replaced
yoast/phpunit-polyfillswithphpunit/phpunitto install the required PHPUnit version, avoiding the need for project-specific polyfills.
- Address issue where a missing file in the underlying Docker image caused
wp-envto crash. #51513
- Execute the local package's
wp-envinstead of the globally installed version if one is available.
- Run
useraddwith-loption to prevent excessive Docker image sizes.
- Remove
afterSetupoption from.wp-env.jsonand theWP_ENV_AFTER_SETUPenvironment variable in favor of more granular lifecycle scripts.
- Add
afterStart,afterClean, andafterDestroylifecycle scripts to a newlifecycleScriptskey in.wp-env.json. - Add a series of
WP_ENV_LIFECYCLE_SCRIPT_environment variables for the various lifecycle scripts. - Rework
runcommand to resolve bugs with non-quoted commands. As a consequence it is no longer possible to pass your entire command towp-envwrapped in double-quotes. Whilenpx wp-env run cli wp helpwill still work,npx wp-env run cli "wp help"will not. If you are currently escaping any quotes you will need to review those commands and ensure they are compatible with this update.
- Support using double dashes in
wp-env run ...to pass arguments that would otherwise be consumed bywp-env. For example, while normally--helpwould provide thewp-envhelp text, if you usenpx wp-env run cli php -- --helpyou will see the PHP help text. - Validate whether or not config options exist to prevent accidentally including ones that don't.
- Support Windows without requiring the use of WSL.
- Docker containers now run as the host user. This should resolve problems with permissions arising from different owners between the host, web container, and cli container. If you still encounter permissions issues, try running
npx wp-env destroyso that the environment can be recreated with the correct permissions. - Remove the
composerandphpunitDocker containers. If you are currently using therun composerorrun phpunitcommand you can migrate torun cli composerorrun tests-cli phpunitrespectively. Note that withcomposer, you will need to use the--env-cwdoption to navigate to your plugin's directory as it is no longer the default working directory.
- Create an
afterSetupoption in.wp-env.jsonfiles for setting arbitrary commands to run after setting up WordPress when usingnpx wp-env startandnpx wp-env clean. - Add a
WP_ENV_AFTER_SETUPenvironment variable to override theafterSetupoption. - Execute the
afterSetupcommand onnpx wp-env startafter the environment is set up. This can happen when your config changes, WordPress updates, or you pass the--updateflag. - Execute the
afterSetupcommand onnpx wp-env clean. - Globally install
composerand the correct version ofphpunitin all of the Docker containers.
- Ensure
wordpress,tests-wordpress,cli, andtests-clialways build the correct Docker image. - Fix Xdebug while using PHP 7.2x.
wp-env run ...now uses docker-compose exec instead of docker-compose run. As a result, it is much faster, since commands are executed against existing services, rather than creating them from scratch each time.- Increase the maximum upload size to 1GB.
- Use test environment's
WP_SITEURLinstead ofWP_TESTS_DOMAINas the WordPress URL. - Automatically add the environment's port to
WP_TESTS_DOMAIN. runcommand now has a--env-cwdoption to set the working directory in the container for the command to execute from.
- PHP 7.3 and 7.4 must use PHPUnit 9.
- It's now possible to run PHPUnit tests on PHP 8.1 and 8.2.
- Query parameters can now be used in .zip source URLs.
- Fix a crash when "core" was set to
nullin a.wp-env.jsonfile. We now use the latest stable WordPress version in that case. This also restores the previous behavior of"core": nullin.wp-env.override.json, which was to use the latest stable WordPress version.
- Previously, wp-env used the WordPress version provided by Docker in the WordPress image for installations which don't specify a WordPress version. Now, wp-env will find the latest stable version on WordPress.org and check out the https://github.com/WordPress/WordPress repository at the tag matching that version. In most cases, this will match what Docker provides. The benefit is that wp-env (and WordPress.org) now controls the default WordPress version rather than Docker.
- Downloading a default WordPress version also resolves a bug where the wrong WordPress test files were used if no core source was specified in wp-env.json. The current trunk test files were downloaded rather than the stable version. Now, the test files will match the default stable version.
- Removed the
WP_PHPUNIT__TESTS_CONFIGenvironment variable from thephpunitcontainer. This removes automatic support for thewp-phpunit/wp-phpunitComposer package. To continue using the package, set the following two environment variables in yourphpunit.xmlfile or similar:WP_TESTS_DIR=""andWP_PHPUNIT__TESTS_CONFIG="/wordpress-phpunit/wp-tests-config.php". - Removed the generated
/var/www/html/phpunit-wp-config.phpfile from the environment.
- Read WordPress' version and include the corresponding PHPUnit test files in the environment.
- Set the
WP_TESTS_DIRenvironment variable in all containers to point at the PHPUnit test files.
- Restrict
WP_TESTS_DOMAINconstant to just hostname rather than an entire URL (e.g. it now excludes scheme, port, etc.) (#41039).
- Removed the need for quotation marks when passing options to
wp-env run. - Setting a
configkey tonullwill prevent adding the constant towp-config.phpeven if a default value is defined bywp-env.
- Added SSH protocol support for git sources
- Added command
wp-env install-pathto list the directory used for the environment. - The help entry is now shown when no subcommand is passed to
wp-env.
- Updated
yargsto fix CVE-2021-3807.
- Fix Xdebug installation code to ensure it would fail gracefully
wp-env destroywill now work in environments which don't include thegreporawkcommands, such as Windows PowerShell.- Fix several permissions issues related to wp-config.php and wp-content files.
- Fix crash which happened when the path to wp-env's home directory contained a space.
- Disable Xdebug 3 for PHP versions less than 7.2 to resolve startup crash.
- Migrate from
nodegittosimple-git. This change now requires you to have agitbinary installed locally to utilize the git sources feature of wp-env.json.
- "mappings" sources are now downloaded if they contain non-local sources.
wp-env startis 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.
- 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.
- Add support for setting the PHP version used for the WordPress instance. For example, test PHP 8 with
"phpVersion": 8.0in wp-env.json. - Add Xdebug 3 to the development environment. You can enable Xdebug with
wp-env start --xdebug(for debug mode) orwp-env start --xdebug=develop,coveragefor custom modes.
- 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.
- The
configandmappingsoptions in.wp-env.jsonare now merged with any overrides instead of being overwritten. - The first listed theme is no longer activated when running wp-env start, since this overwrote whatever theme the user manually activated.
wp-env startno longer stops the WordPress instance if it was already started unless it needs to configure WordPress.wp-env startno longer updates remote sources after first install if the configuration is the same. Usewp-env start --updateto update sources.
- You may now specify specific configuration for different environments using
env.testsorenv.developmentin.wp-env.json. wp-env startis significantly faster after first install.
wp-env destroynow removes dangling docker volumes and networks associated with the WordPress environment.
- Add support for running interactive commands. Examples:
wp-env run cli wp shellandwp-env run cli bash. - View php and WordPress log output with the new
wp-env logscommand. - Clean up your local environment with the new
wp-env destroycommand. - Expose Docker service for running phpunit commands.
- You may now mount local directories to any location within the WordPress install. For example, you may specify
"wp-content/mu-plugins": "./path/to/mu-plugins"to add mu-plugins.
- URLs for ZIP files are now supported as core, plugin, and theme sources.
- The
.wp-env.jsonconiguration file now accepts aconfigobject for settingwp-config.phpvalues. - A
.wp-env.override.jsonconfiguration file can now be used to override fields from.wp-env.json. - You may now override the directory in which
wp-envcreates generated files with theWP_ENV_HOMEenvironment variable. The default directory is~/.wp-env/(or~/wp-env/on Linux). - The
.wp-env.jsonconiguration file now acceptsportandtestsPortoptions which can be used to set the ports on which the docker instance is mounted.
wp-env startno longer accepts a WordPress branch or tag reference as its argument. Instead, create a.wp-env.jsonfile and specify a"core"field.wp-env startwill now download WordPress into a hidden directory located in~/.wp-env. You may delete your{projectName}-wordpressand{projectName}-tests-wordpressdirectories.
- A
.wp-env.jsonconfiguration file can now be used to specify the WordPress installation, plugins, and themes to use in the local development environment.
- When running scripts using
wp-env run, the output will not be formatted if not written to terminal display, resolving an issue where piped or redirected output could be unintentionally padded with newlines.