Windows

This article will try to help you set up a development environment on your Windows machine. The assumption will be that you are trying to either contribute to the framework or build a plugin using it (and thus following all the standards laid out by the framework).

There is no guarantee that this will work. We can't account for software conflicts or misconfigurations present on your machine, but this should point you at least in the right direction.

Development folder

You're obviously free to organize your project files however you want, but we have a few suggestions that have worked well for us (since you're on Windows, especially). Namely, in your home directory, create a new folder called Source. We also change its icon to this for easy recognition (place the icon file inside the folder):

105KB

git-for-windows.ico

image

Source folder icon

Inside the Source folder, we usually create 3 new ones: Tools, Framework, and Plugins. Of course, your choice may vary based on what you want to do.

Linux Subsystem for Windows

Although we're running on Windows, the Linux Subsystem for Windows (WSL for short) is what we'll be using to install most software. If you are already familiar with the Linux command line, this should all feel pretty familiar.

Microsoft has a great article already explaining how to enable WSL and how to install your distribution of choice. In the spirit of not reinventing the wheel, just follow the steps from here. We recommend using WSL 2 and installing the Ubuntu 20.04 LTS distribution once you reach that step, but any distribution should do.

The article also mentions that you can optionally install Windows Terminal to run PowerShell and WSL side-by-side. You don't have to, but we find it handy especially when using VVV for testing.

Install DevKinsta

For automated testing, you will need a running web server. For this task, we highly recommend DevKinsta although any tool like Local by Flywheel, VVV or even plain old WAMP will do. If you move forward with VVV and followed our dev folder structure from above, VVV would belong into the Tools folder.

DevKinsta has a great guide on how to install it right here. Due to the virtualization nature of WSL2, your local environment is likely to be rather slow. Currently there is no known workaround and while it is annoying, it's usually fast enough for most purposes.

Each module's tests folder contains an extra README.md file explaining how to set it all up to run tests on your local machine. WP-Browser also has some useful tutorials (albeit you need to selectively pick what applies) for VVV, for WAMP, and for Local by Flywheel.

Unless explicitly mentioned otherwise, all the steps outlined below should be performed in your WSL terminal.

Install PHP7.4

While not strictly required to use 7.4, it is best to use a still supported version. If you followed our recommendation and installed Ubuntu, here is an article explaining how to install PHP. If you installed a different distribution, at the bottom of the article you will find links to instructions for other systems.

Since we will not be using WSL as a server, you don't need to follow the instructions about setting up nginx or PHP-FPM. Vanilla PHP7.4 will do.

Install Composer and Node.js

As the PHP dependency manager, you will need to install Composer on your WSL. Here is an article explaining how to install Composer on Ubuntu 20.04 together with links to other versions and distributions. The article show the installation of Composer 1.10, but you'll likely end up with Composer 2. That is fine and even recommended. If not, run composer self-update after the installation.

Optionally, you can go ahead and install Node.js and its companion dependency manager, npm. An article describing this procedure for Ubuntu 20.04 is here. Node.js and npm are not strictly necessary for using the framework, but they do enable the use of task runners and thus easy compilation of TypeScript and Sass code and other automatable tasks. If you're doing that some other way already (or don't need/want that at all), feel free to skip this step.

Install Git

For version control, we use git. Hence it is a good idea to install it on your WSL distribution. Here is an article describing to how to that on Ubuntu 20.04.

However, the git command line is notoriously complicated. We strongly recommend you use a GUI instead, like GitKraken (which is available for Windows, MacOS, and Linux -- in this case, you should download the Windows version for your main OS). It's a good idea to install git on WSL regardless though, just in case you'll need it at some point.

Convenience stuff

You can choose to edit your .bashrc file to include the following commands:

# go to the Source folder on startup
cd /mnt/c/Users/<YOUR WINDOWS USER NAME>/Source

# store the Windows host IP
export WINDOWS_HOST_IP=`cat /etc/resolv.conf | grep nameserver | cut -d ' ' -f 2`

You're done!

Congratulations! Your dev environment is set up. It's time to open up your favorite IDE (we recommend PhpStorm) and try out all your fancy new tools by setting up your first plugin project!