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 (
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
wp-config.php file back into the
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
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
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
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
The following lines set these the environment variables
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.
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 firstname.lastname@example.org: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
Whenever you are making changes, you’ll want:
grunt watchrunning from the
public/directory in a non-SSHed in terminal (e.g. in
~/Local Sites/wpcore/app/publicon your machine)
- An “Open Site SSH” terminal, where you’ve used the Local by Flywheel User Interface to SSH (e.g. in
~/app/publicon the website)
- Note: In my experience, if you simply run
phpunitfrom the command line you’ll get a lot of Errors and Failures.
- I always use
phpunit --filterto run the tests for a single class (e.g.
phpunit --filter Tests_Avatar)
- Note: In my experience, if you simply run