WordPress Core Development on Local by Flywheel

I use Local by Flywheel for my local WordPress development. In preparation for of contributing to WordPress core (I’ve done this before but it has been awhile and I was using VVV), I setup a site on my Local by Flywheel install for this purpose. Because setting up a site for WordPress core development on Local by Flywheel is different than setting up a normal development site, this is my documentation of the process.

Note: You can jump to the Summary of Installation Commands if you’re familiar with the command line, Local by Flywheel, and want the short version.

Step 1: Create a Site in Local by Flywheel

I’m creating a site called wpcore that loads on my local machine at wpcore.test.

When creating my site, I opt for a Custom Environment, which gives me extra flexibility and installs Xdebug. If you’re on a low-bandwidth environment you can use the Preferred option (which does not download anything additional to create a Local by Flywheel website).

On the final setup screen, I use the default WordPress username and password (admin / password).

At this point, going to wpcore.test on my local machine loads a WordPress website.

Step 2: Make a copy of wp-config.php

We are going to replace everything in the app/public directory of our site but first, we copy wp-config.php to a safe spot for re-use later (specifically, I’m copying the wp-config.php file one level up into the app/ folder. I’m on a Mac and using the Terminal app, I go to the wpcore/app/ directory (Note: I am accessing these files on my Mac, I did not use Local by Flywheel’s “Open Site SSH” (yet, this step comes later).

cp public/wp-config.php ./

Step 3: Replace the public folder

Next I delete the public/ folder and replace it with a cloned copy of https://github.com/WordPress/wordpress-develop/.

Remove the public folder

rm -rf ./public

Clone WordPress Develop Git Repo

git clone https://github.com/WordPress/wordpress-develop/ public

Step 4: Return wp-config.php

Move the wp-config.php file back into the public directory.

mv wp-config.php ./public/

Step 5: Download setup-phpunit.sh

Next download setup-phpunit.sh for later use.

curl -o setup-phpunit.sh https://gist.githubusercontent.com/keesiemeijer/a888f3d9609478b310c2d952644891ba/raw/

Step 6: Build WordPress

In WordPress Ticket 43055 a build process was introduced, so while all development changes are made in the /src directory a grunt task builds all of the code and you actually run WordPress from the /build directory.

This is done from within the public directory with npm and grunt.

cd public
npm install && grunt build

If you don’t already have npm installed on your machine, you will have to install npm. (You don’t have to explicitly install Grunt, that is done by npm install when you run it.

Step 7: SSH into the Website

At this point, we right-click the site name (“WPCORE”) in the Local by Flywheel User Interface and click the “Open Site SSH” option.

All of the following commands are run over SSH (i.e. within the website).

Step 8: Build WordPress

As mentioned earlier, when developing for WordPress core the files we execute are in the /build directory. To configure our site update both the siteurl and the home options in the database table (wp_options) by appending /build to them.

We can do this from the SSH command line using the following WP CLI command.

wp option update siteurl "$(wp option get siteurl)/build";wp option update home "$(wp option get home)/build"

If you do update your database manually, you should see something like this

Success: At this point, you should be able to go to wpcore.test/build on your local machine and see the WordPress website. You can also log in at wpcore.test/build/wp-admin

Step 9: Add PHPUnit for Testing

A big part of WordPress code is automated tests. In order to run these tests, we install PHPUnit and a copy of our database for testing.

Step 9a: Create wp-tests-config.php

The database settings for our test database go in wp-tests-config.php. To create this file with the correct values we run

sed -e 's/yourusernamehere/root/g' -e 's/yourpasswordhere/root/g' -e 's/youremptytestdbnamehere/wordpress_test/g' wp-tests-config-sample.php > wp-tests-config.php

which copies wp-tests-config-sample.php and updates the username, password, and database name values.

Step 9b: Set Environment Variables

WordPress looks for two environment variables when running tests WP_TESTS_DIR and WP_CORE_DIR.

The following lines set these the environment variables WP_TESTS_DIR and WP_CORE_DIR in our .bashrc file, so the values will persist when the website is stopped and started.

echo 'export WP_TESTS_DIR=/app/public/tests/phpunit' >> "$HOME/.bashrc"
echo 'export WP_CORE_DIR=/app/public/build' >> "$HOME/.bashrc"
source ~/.bashrc

Step 9c: Setup PHPUnit

Earlier we downloaded setup-phpunit.sh. Now we’re going to run this setup.

bash setup-phpunit.sh

Summary of Installation Commands

From your host machine

From your host machine (i.e. not SSHed into the Local by Flywheel website) starting in the app/ directory (e.g. ~/Local Sites/wpcore/app) run these commands

cp public/wp-config.php ./
rm -rf ./public
git clone git@github.com:WordPress/wordpress-develop.git public
mv wp-config.php public/
curl -o setup-phpunit.sh https://gist.githubusercontent.com/keesiemeijer/a888f3d9609478b310c2d952644891ba/raw/
cd public/
npm install && grunt build

Open Site SSH

Use the “Open Site SSH” menu item after right clicking the site name in the Local by Flywheel User Interface, then run these commands

cd app/public
wp option update siteurl "$(wp option get siteurl)/build";wp option update home "$(wp option get home)/build"
sed -e 's/yourusernamehere/root/g' -e 's/yourpasswordhere/root/g' -e 's/youremptytestdbnamehere/wordpress_test/g' wp-tests-config-sample.php > wp-tests-config.php
cd ../
echo 'export WP_TESTS_DIR=/app/public/tests/phpunit' >> "$HOME/.bashrc"
echo 'export WP_CORE_DIR=/app/public/build' >> "$HOME/.bashrc"
source ~/.bashrc
bash setup-phpunit.sh

Making Changes

Whenever you are making changes, you’ll want:

1. grunt watch running from the public/ directory in a non-SSHed in terminal (e.g. in ~/Local Sites/wpcore/app/public on your machine)
2. An “Open Site SSH” terminal, where you’ve used the Local by Flywheel User Interface to SSH (e.g. in ~/app/public on the website)
   • Note: In my experience, if you simply run phpunit from the command line you’ll get a lot of Errors and Failures.
   • I always use phpunit --filter to run the tests for a single class (e.g. phpunit --filter Tests_Avatar)

Photo Credit

Wikimedia Commons

Sal Ferrarello (@salcode)

Sal is a PHP developer with a focus on the WordPress platform. He is a conference speaker with a background including Piano Player, Radio DJ, Magician/Juggler, Beach Photographer, and High School Math Teacher. Sal can be found professionally at WebDevStudios, where he works as a senior backend engineer.