This page describes the process of how we setup development environments at Yoast.
Note: These instructions assume you're working with OSX.
Table of contents
- Getting started
- Organizing your projects
- Setting up PHPUnit
- Installing the plugins
- Linking repositories via Yarn
- Now what?
Before you start contributing to the Yoast plugins, ensure you've checked out our development tools page which lists the various tools that need to be used (unless otherwise noted).
Organizing your projects
Generally speaking, we advise people to create a
Yoast folder in their
Documents directory to keep all things together. After this, you have two flavors:
- Clone plugins on an environment-by-environment basis, which allows you to have various versions of the same plugin on your system, without them (possibly) conflicting.
- Clone all plugins into a single directory and symlink them to the development environments. This results in the same version (branch) running across all development environments that were linked.
Note: The first option is preferable, as there's a lower chance of messing things up.
In your terminal,
cd to the newly created
Yoast directory. In there, you should locate the VVV directory and navigate to
<your VVV directory>/www/wordpress-default/public_html/wp-content/plugins where you can clone the various plugin repositories.
Setting up PHPUnit
Making it work with WordPress
When developing, it's also necessary that you add and run tests before submitting a PR. To be able to do this, we use PHPUnit to create and run tests. Before being able to run PHPUnit, you'll have to configure a few things.
First, you should edit your local
.zshrc configuration file (via
vim ~/.zshrx or a similar editor) and add the following lines:
export WP_PLUGIN_DIR="/dir/to/plugin/directory" export WP_DEVELOP_DIR="/dir/to/wp/develop/directory"
Note: Make sure to reload your terminal once you've added the above lines.
wordpress-develop) should point to a
trunk build of WordPress. In the older VVV instances this defaulted to
wordpress-develop, in the newer this is
wordpress-trunk. If afterwards you get an error in PhpStorm saying you can not connect, the test database needs to be set up.
- The sample configuration is located in
wordpress-trunk/public_html/wp-tests-config-sample.php. Copy the sample to
- Fill in the configuration with valid data. Create the database manually, if needed (you can use Sequel Pro or PHPMyAdmin). Mind the
$table_prefixvariable in the configuration here. By default it is set to
- Important: Ensure that the
DB_HOSTpoints to the Vagrant box URL
vvv.testsince this is run from your local machine (in PhpStorm), not from the Vagrant box itself.
Enabling PHPUnit in PhpStorm
The setup in PhpStorm can be completed by following the next steps:
- Under the Run menu in PhpStorm, go to
- In the following window, press the
+in the left corner and choose PHPUnit in the options.
- Select the option:
Defined in the configuration pageand check the checkbox for
Use alternative configuration file.
- Behind the checkbox, enter the full path to the
phpunit.xml.distfile. This file is located in the plugin directory. If the repository contains a
phpunit.xmlfile, use that one instead. (i.e wordpress-seo has two types of tests. Use
phpunit-integration.xml.distfor the 'old' integration tests, and
phpunit.xml.distfor the BrainMonkey tests.)
- Now you've entered the path, press the icon on the far right. This will bring you to the
- Press the plus icon and select the first option:
PHPUnit Local. Select
Path to phpunit.pharand enter the path to the file. It's probably in your
/Cellardirectory. If you do not have a
phpunit.pharfile yet, you can download it here: https://phar.phpunit.de/
- Finally, when you return to the
Run/Debug configurationswindow, there might be an error message at the bottom. Press the
Fixbutton next to it and select PHP as your CLI interpreter. Apply and done!
Running multisite tests
Some of our plugins contain tests that are only run on multisite. To run those tests, select your PHPUnit configuration and add the
WP_MULTISITE flag with value
1 in the command line section of the settings.
Installing the plugins
All the following directories are relative to the directory in which you have installed Vagrant.
To have the complete set of Yoast plugins, clone the following repositories in your:
Yoast SEO with the addons:
For each of these add-ons, run
composer install and
yarn in the respective directories to make sure all dependencies are installed.
- https://github.com/Yoast/yoast-plugin-toggler - Switch between Yoast SEO Free and Premium
- https://github.com/Yoast/yoast-acf-analysis - Provide compatiblity with Advanced Custom Fields
- https://github.com/Yoast/yoastseo-amp - Provide additional functionality for The AMP plugin
All our publicly accessible repositories can be found on GitHub
Linking repositories via Yarn
Follow these steps to link YoastSEO.js to your WordPress environment:
- Check out the branch you want to link in the yoastseo.js folder
yarn installin the yoastseo.js folder
yarn linkin the yoastseo.js folder (once, but more can't hurt, to register the repository as linkable to Yarn)
yarn link yoastseoin the wordpress-seo directory in
grunt build:jsin the wordpress-seo folder.
After you've cloned the repositories, you can navigate to
local.wordpress.test in your browser to see the development environment. Open the plugin directory in your IDE and you should be ready to develop!