This extension configures a Chassis virtual machine for WordPress core development.
Clone Chassis into the directory of your choice with this command:
# You may change core-dev-vm to the folder name of your choice.
git clone --recursive https://github.com/Chassis/Chassis core-dev-vm
Next, create an empty config.local.yaml
file in the root of the Chassis checkout, and paste in these options:
# Specify the .local hostname of your choice.
hosts:
- core.local
paths:
# Use Chassis paths as normal,
content: content
base: .
# Except use your checkout for the WordPress directory. To switch
# between /src and /build, edit this line then run `vagrant provision`.
wp: wordpress-develop/src
# Instruct Chassis to use this extension.
extensions:
- core_dev
# Set a PHPUnit version.
phpunit:
version: 7.5
(Other Chassis configuration options may be used as normal, so long as the above paths are provided correctly.)
After creating this file, run vagrant up
to initialize the virtual machine.
Once provisioned, your new WordPress development site will be available at core.local, and you may login at core.local/wp with the username admin
and password password
. The site will be using the /src
build of the wordpress-develop
repository, newly cloned on your host system at [Chassis root]/wordpress-develop
and available as /vagrant/wordpress-develop
inside the virtual machine.
To switch the site to use the build
version of the site instead, edit the wp:
line in your config.local.yaml
to end in "build" instead of "src" then run vagrant provision
.
PLEASE NOTE: The provisioner will run npm install
and grunt
for you after cloning the repository, so you can get started right away. However, subsequent npm
or grunt
commands are left to you, the developer. If you have made changes to the code and are using the /src
directory, run grunt build --dev
to rebuild the project into the /src
directory if you do not see your changes. If you are using /build
, run grunt
or grunt build
. See the WordPress core contributor handbook for more information on building & developing WordPress.
(Commands may be run either within the Chassis VM — e.g. vagrant ssh -c 'cd /vagrant/wordpress-develop && grunt build --dev'
— or else you may run npm install
within your host operating system and run the builds with grunt
locally on your machine. Builds may be faster on the host system than within the VM, but using the VM's versions of Node and Grunt means you need less tooling installed outside Chassis.)
You may already have wordpress-develop
checkout out locally using git
or svn
. You may choose to use this repository within your VM instead of cloning a fresh copy by mapping the directory into your virtual machine using synced_folders
.
As an example, imagine that you have your Chassis box checked out in ~/core-vm
, and your WordPress development repository checked out in ~/wordpress-develop
. In your config.local.yaml
file inside the Chassis directory, tell Chassis to sync the folder ../wordpress-develop
into the VM as /vagrant/wordpress-develop
.
hosts:
- core.local
paths:
# Use the normal Chassis directory structure,
content: content
base: .
# Except use your checkout for the WordPress directory. To switch
# between /src and /build, edit this line then run `vagrant provision`.
wp: ../wordpress-develop/src
synced_folders:
# This will allow you to run the WP unit tests against your existing
# wordpress-develop repository checkout.
../wordpress-develop: /vagrant/wordpress-develop
extensions:
- core_dev
From the host machine, use vagrant ssh
to run the unit tests inside the virtual machine:
vagrant ssh -c 'cd /vagrant/wordpress-develop && phpunit'
To run a particular suite of tests, for example just the tests defined within the WP_Test_REST_Posts_Controller
class, provide that class name with --filter
:
vagrant ssh -c 'cd /vagrant/wordpress-develop && phpunit --filter WP_Test_REST_Posts_Controller'
The best version of PHPUnit to install depends on the version of PHP you are using:
- PHP 5.6: PHPUnit 4.8
- PHP 7.0: PHPUnit 6.5
- PHP 7.1+: PHPUnit 7.5
Define a core_dev
key in your config.local.yaml
to configure this extension.
# config.local.yaml
core-dev:
# If the wordpress-develop repo is not already checked out within the
# Chassis root directory, this extension will clone a fresh copy for
# you. To add a "mirror" remote pointing to your own fork of the develop
# repo, specify your fork's address in the `mirror` option.
mirror: git@github.com:{your GitHub name}/wordpress-develop.git
There are some other useful Chassis extensions that can help to make core contributions easier. We recommend the following extensions:
- Imagick - Imagick speeds up image processing and allows permitting better testing of media component work.
- Intl - A Chassis extension to install and configure Intl on your server.
- BC Math - BCMath provides arbitrary precision mathematics.
- MailHog - Catch all the emails WordPress sends while you're developing using Chassis!
- XDebug - Xdebug is an extension for PHP to assist with debugging and development.
- WP_CLI - A Chassis extension to automate the installation of WP-CLI packages.
- Whoops - A Chassis extension to install Whoops for PHP error reporting.
- Debugging - A Chassis extension to install and activate common WordPress plugins used for debugging during development.