WordPress Local Environment

The e2e test infrastructure was recently introduced to WordPress CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress., using Docker to create a local WordPress environment for running the tests.

Almost immediately, folks started trying to use it as a full local development environment, which is a pretty good indication that we should make that easier. 🙂 #47767 is a complete rebuild of the e2e environment, turning it into a dedicated development environment, that also happens to function as an e2e environment. 🎉

The Goal

As we discovered with the GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/gutenberg/ local environment, trying to make a shell script based do-it-all tool results in a sub-par experience for everyone. It’s difficult for such a tool to work well across all use cases: if it tries to handle common problems automatically, it will cause problems for regular contributors. If it does the bare minimum, it will be unusable for infrequent contributors. There doesn’t appear to be a happy middle ground.

As such, the idea with this new tool is to allow setting up a local development environment by running as few commands as possible, providing sensible defaults, but allowing as much customisation as possible. This gives a solid base for regular contributors to work from (particularly when testing against uncommon configurations), but also provides room for an external tool that provides new contributors with a seamless experience.

Infrastructure

In order to make this work as cleanly as possible, there are custom Docker images configured for running WordPress. They work for all versions of PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 7.4 or higher from 5.2 to 7.3, allowing easy testing of different PHP versions. The image definitions are generated and committed to the wpdev-docker-images GitHub repository, they’re then built and deployedDeploy Launching code from a local development environment to the production web server, so that it's available to visitors. to Docker Hub by Travis.

These images aren’t intended for folks that wish to host Docker-based WordPress sites. Their primary focus is on creating a WordPress development environment.

Using

This tool currently isn’t optimised for inexperienced contributors. Setting it up and using it requires some familiarity with both Docker and the command line.

First off, you’ll need to install Docker.

• Windows 10 Pro/Education/Enterprise: Docker Desktop for Windows
• Windows 7, 8, and 10 Home: Docker Toolbox
• macOS Sierra (10.12) and newer: Docker Desktop for Mac
• macOS 10.8-10.12: Docker Toolbox
• Linux: See the documentation for installing Docker on your distro.

You’ll also need a recent version of Node. We rarely bump the minimum version of Node required, so if you don’t have a particular need for switching Node versions, installing the latest LTS version is probably the easiest option.

Following that, you’ll need to run npm install to download some build tools that WordPress needs, then npm run env:start will start the server at http://localhost:8889. npm run env:install will set up a clean installation, with the user adminadmin (and super admin) and the password password.

Congratulations! You can now work on WordPress! Here are some extra commands that will help you along the way:

npm run env:stop

If you prefer to stop your Docker containers when you’re not using them, this command will stop them. You can always restart them by running npm run env:start again.

npm run env:clean / npm run env:reset

These can be used to clean up your development environment if things aren’t working correctly. The former will delete the database and some temporary files, while the latter will remove all images, so the next time you run npm run env:start, they’ll be downloaded fresh.

npm run env:logs

Shows the logs server logs.

npm run env:cli

This will run WP-CLI. Where the WP-CLIWP-CLI WP-CLI is the Command Line Interface for WordPress, used to do administrative and development tasks in a programmatic way. The project page is http://wp-cli.org/ https://make.wordpress.org/cli/ documentation mentions running wp, run npm run env:cli instead. For example, npm run env:cli help.

npm run test:php / npm run test:e2e

These commands will run the PHPUnit and E2E test suites, respectively.

Configuring

You can also customise the development environment by setting particular environment variables before starting it. After changing any of these settings, you’ll need to run npm run env:stop then npm run env:start before they take effect.

Each OS has a slightly different way of setting environment variables. In these examples, substitute VARIABLE_NAME for the name of the setting you want to change, and value for the value you want to set it to.

Linux, macOS, and WSL: export VARIABLE_NAME=value
Windows (DOS/CMD.exe): SET VARIABLE_NAME=value
Windows (PowerShell): Set-Item Env:VARIABLE_NAME=value

LOCAL_PORT

Change the port number that the site will be available on. You’ll need to run npm run env:install after changing this.

LOCAL_DIR

Change whether the site runs from the src or build directory.

LOCAL_PHP

The PHP version to use when running the site. Valid options are ‘latest’, and ‘{version}-fpm’, where ‘{version}’ is any x.y PHP version from 5.2 onwards.

LOCAL_PHP_XDEBUG

Set to true or false to enable or disable the XDebug module in PHP.

LOCAL_MYSQL

The MySQL version to use. See https://hub.docker.com/_/mysql/ for valid versions. If you downgrade the MySQL version, you may need to run npm run env:clean to reset the MySQLMySQL MySQL is a relational database management system. A database is a structured collection of data where content, configuration and other options are stored. https://www.mysql.com/. data files.

LOCAL_WP_DEBUG / LOCAL_WP_DEBUG_LOG / LOCAL_WP_DEBUG_DISPLAY / LOCAL_SCRIPT_DEBUG

The debug settings to add to wp-config.php. Set to true or false to change their corresponding debug setting. If you already have a site up and running, it may be easier to just edit these in the wp-config.php file.

What’s Next?

Right now, this has only been committed to trunk. It can soak there for a bit, ensuring it works well for everyone.

Following that, it will be backported to all branches back to WordPress 3.7. Since this is the oldest version we still occasionally make releases for, there’s no value in porting it further back. Importantly, since the Security Team is evaluating ceasing backporting of security fixes to WordPress 3.7, it’s likely that we’ll need to be doing work on that branchbranch A directory in Subversion. WordPress uses branches to store the latest development code for each major release (3.9, 4.0, etc.). Branches are then updated with code for any minor releases of that branch. Sometimes, a major version of WordPress and its minor versions are collectively referred to as a "branch", such as "the 4.0 branch". to both inform and help site owners upgrade. Having a working development environment makes this a much less painful task.

I’ve been sporadically working on a tool called TestPress, which is intended to make the experience of contributing to WordPress as seamless as possible, particularly for new and non-developer contributors. It hasn’t been updated to make use of this new local environment yet, but that’s high on my todo list. For folks who aren’t comfortable downloading and installing Docker, managing Node versions, or working on the command line, TestPress manages all of that for you. I’ll have more to write about TestPress when it’s in a more usable state. 🙂

That’s about it! Please test and report bugs as you find them! 🐛

#core