As I worked through the homework challenge round at one of the companies I interviewed at (a company that was very WordPress-centric), I found myself struggling with literally every step – trying to find shreds of information on how to do the most basic things. Things like building a simple local test environment. I found information telling me I could use – a local installation – vvv – wp-env Now, for a variety of reasons that aren’t important for this post, I settled on wp-env. But almost NOWHERE could I find explanations for where your directories are and how wp-env works. Nothing about the default directories, how to make basic modifications, the kinds of parameters wp-env could/would take, and so on. After a lot of digging and more than a little begging/bribing of some of my people resources, I collected the information I needed to finish the homework challenge (you can read the fruits of that labor ). here But I also realized that plenty of other folks might need lesson-behind-the-lesson, the how-to that allowed me to create the piece I was actually trying to write. So I thought I’d share some of my discoveries, in case your work has brought you to a similar point of frustration and lack of knowledge. Before I start, here are the assumptions making: I’M Because your setup might be (“might be?!?” How about “is almost certainly!”) different than mine, here’s what I’m working with. If your situation is different, adjust as needed: Ubuntu 23.10 (Mantic Minotaur) AMD Ryzen 7 with 16 cores 64Gb RAM Installing wp-env With that out of the way, to install wp-env itself, you need the following: docker (I found good instructions ) here node.js (instructions ) here and finally, wp-env, by running: npm -g i @wordpress/env The Most Important Thing Most people need more than one WordPress environment at the same time, and those environments have to remain completely separate. That should provide you with the context you need to understand the single most important thing I learned: Whatever directory you are in when you start wp-env, THAT is the directory wp-env is tied to. What I mean is: Let’s say you have that if you have two directories: /foo and /bar Today, you are in /foo and start wp-env you make a bunch of changes, install some plugins, etc. Tomorrow, you are in /bar and start wp-env You will think ALL YOUR CHANGES ARE GONE. They are not. Stop wp-env, change to the /foo directory, and start wp-env again. You’ll see all the changes from yesterday. You actually don’t even need to stop wp-env from the /bar directory. You can have both running at the same time. This is a feature, not a bug. Each directory in which you start wp-env has its own dedicated environment. It allows you to test and develop multiple environments without them stomping all over each other. The Other Most Important Thing Most people install wp-env to test out a plugin – one they want to try or one they’re building themselves – which should give you context for the next most important thing I can tell you: The directory you are in when you start wp-env (/foo or /bar or whatever) is treated like /wp-content/plugins/ . new-plugin-name The rest of the WordPress installation will be in your home directory under . ~/wp-env Quick-And-Dirty-wp-env With those two important things out of the way, you have most of the information you need to get started. You kick off wp-env by going into the directory you want to associate with this development environment (as explained earlier) and typing: wp-env start That’s it! Well, that’s it in terms of what you TYPE. But after that, you’ll probably see a message or two. Most of the time, it’s just telling you about a file or two it was expecting but couldn’t find (more on that later), etc. Nothing to worry about, really. Also, the first time you run wp-env on your machine EVER, you’ll see the messages about downloading the actual docker container that has the base WordPress image. But after all that, assuming you don’t run into any show-stopping issues, you’ll see a message telling you WordPress is now running on your machine at a particular port. If you browse to that address, you’ll see WordPress running. More to the point, you can log into the admin panel by going to (the address wp-env showed you)/wp-admin. You can log in with the username and the password . admin password Before you panic about how insecure that is, remember this is running exclusively on your system. OK, you can panic now and change that password!! Then, you can start playing around, developing your plugin, or doing whatever it is you need out of this test environment. Jane! Shut Off This Crazy Thing!! If you need to shut down your environment, run the command: wp-env stop Remember to be in the directory where you started, or you could end up shutting down the wrong environment! What the Docs Don’t Tell You (Or don’t tell you clearly enough. Or maybe it’s just me.) For the most part, running is all you need. wp-env start But occasionally, you’ll need to make other adjustments. One situation I ran into was that the default version of PHP (7.4) wasn’t compatible with the plugin I was developing. But it turns out you can start wp-env with all sorts of optional elements. Like specifying the PHP version you want: WP_ENV_PHP_VERSION=8.1 wp-env start The trick here is to indicate the MAJOR version of PHP. So you can’t specify 8.1.3. In reality, this relates to the various docker images available for WordPress (which you can find ). here By default, wp-env will start the website on port 8888. But if you need it to be on a different port, you can be specific. WP_ENV_PORT=3333 wp-env start But you don’t have to do everything on the command line. You can also put all the settings in a file named and save that into the same directory where you’d run in the first place. .wp-env.json wp-env That explains the startup error (really just error-ish) message you saw earlier. For more details, check out the “.wp-env.json” section of . this page Troubleshooting and Other Swearwords “Screws fall out all the time. The world is an imperfect place” – John Bender, “The Breakfast Club” Here are a few things you can do if things haven’t run the way you wanted or expected. You can see if the WordPress container is running at all by using the command . docker ps You can restart the WordPress environment and update everything to the latest version with the command wp-env start --update If you want to completely clean out the database(s), use the command . wp-env clean all And if you want to blow away the entire wp-env instance and start over, use wp-env destroy The Mostly Un-Necessary Summary Developing new features, plugins, or improvements in WordPress is challenging enough without also having to slog through figuring out how to even get a test environment established. Hopefully, this post has helped shorten your time to “Hello world” a little bit. Also published . here

Walkthroughs, tutorials, guides, and tips. This story will teach you how to do something new or how to do something better.

Too Long; Didn't Read

Get VPN and ad blocker with a single subscription	

Figuring Out wp-env: Your Guide to Setting Up a WordPress Test Environment

Too Long; Didn't Read

Leon Adato

STORY’S CREDIBILITY

Guide

Share Your Thoughts

About Author

TOPICS

THIS ARTICLE WAS FEATURED IN...

Figuring Out wp-env: Your Guide to Setting Up a WordPress Test Environment

Too Long; Didn't Read

Leon Adato

STORY’S CREDIBILITY

Guide

Share Your Thoughts

About Author

TOPICS

THIS ARTICLE WAS FEATURED IN...

RELATED STORIES