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:
grunt watch
running from thepublic/
directory in a non-SSHed in terminal (e.g. in~/Local Sites/wpcore/app/public
on your machine)- 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
)
- Note: In my experience, if you simply run
@Sal Ferrarello, You made my day as I was looking to set it up with Local by FlyWheel.
Thank you so much for such detailed tutorial to set it up.