WordPress Coding Standards from the Terminal

This article will show you how to add the tools you need to test your code against the WordPress Coding Standards from the Command Line.

A second article will be published shortly with instructions for adding them to the code editor Atom. It will also include links to the instructions for other editors.

Going by the length of the page, this process may seem like quite a big effort, but starting to follow Coding Standards has many advantages and it will be time well invested!

The WordPress Coding Standards

As explained in the Make WordPress – Core Developer Handbook, the WordPress Coding Standards were developed by the community with the aim to “ensure that files within the project appear as if they were created by a single person.“

The advantage of this is that it is easier to read the code and, therefore, maintain it.

But apart from style guidelines, the Coding Standards also provide best practice recommendations that will help you avoid common coding errors and, therefore, improve the quality of your work.

The WordPress Coding Standards encompass guidelines for PHP, JavaScript, HTML, CSS and Accessibility.

From the Command Line

There are many ways of testing your code against the WordPress Coding Standards. In this section, we will look at how to install and use the Tools we need to do so from the Command Line.

Some of these will also need to be installed if you were to use them from your code editor, so I’d encourage you to read on and try them out!

PHP

We will use the Squizlabs PHP_CodeSniffer (PHPCS) to test our PHP code. Please refer to the WordPress Coding Standards for PHP_CodeSniffer page for detailed instructions on how to install PHPCS and set it to use the WordPress Coding Standards.

To add your PHPCS directory to your PATH environment variable, type the following command from the Terminal:

export PATH="~/projects/phpcs/bin:$PATH"

Assuming you have installed PHPCS in a folder called projects, as in the example given in the instructions.

After this, you can start checking your PHP code against the WordPress Coding Standards. To do so, go to the directory where the PHP file is and type this command:

phpcs --standard=WordPress filename.php

For example:

For each error or warning, PHPCS gives us the line number where the error or warning occurs and a brief description.

You will notice that some of them also have a little [X] sign. This indicates that the error can be fixed automatically without opening the file. Run the following command to fix these errors automatically:

phpcbf --standard=WordPress filename.php --suffix=.fixed

This creates a new file called filename.php.fixed with the errors fixed. If you prefer the fix to override the original file directly, simply leave out the --suffix=.fixed part of the command.

PHPCBF, by the way, stands for PHP Code Beautifier and Fixer and comes with the default PHPCS installation.

JavaScript

We will need to install ESLint and eslint-config-wordpress with NPM for each project with JavaScript code to be checked against the WordPress Coding Standards.

If you don’t have npm in your machine yet, please follow the steps 1.1. and 1.2. from the installation instructions .

Once npm has been installed, run the following command to install the ESLint package globally:

npm install eslint -g

Please note that, the steps up to here will only need to be done once. The steps that follow, however, will need to be carried out for every project you want to check against the WordPress Coding Standards.

To finish the ESLint installation process, follow the instructions in step 2.1. from the official installation instructions.

Instead of continuing onto step 2.2, open your new package.json file with your code editor and add a comma at the end of the second last closing curly bracket, and press Enter to add a new line. On this new line, add the following code:

"eslintConfig": {
   "extends": "wordpress"
}

package.json should look something like this:

{
  "name": "demo-files",
  "version": "1.0.0",
  "description": "Demo files to demonstrate implementation of the WordPress Coding Standards",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "Carme Mias",
  "license": "GPL-2.0",
  "devDependencies": {
    "eslint": "^5.8.0",
    "eslint-config-wordpress": "^2.0.0"
  },
  "eslintConfig": {
    "extends": "wordpress"
  }
}

Save the changes before closing the editor. We can now start using ESLint.

To do so, simply type the following command from Terminal:

eslint filename.js

The result will give us the line number where the error occurs, as well as the error title and a brief description.

If some of the errors can be fixed automatically, we can do so with this command:

eslint filename.js --fix

CSS

To check our CSS code, we will install the Stylelint npm package both as global and a dev dependency.

To do so, open your Terminal and type:

npm install stylelint -g

Then, from the directory where the files to be checked are:

npm install stylelint stylelint-config-wordpress --save-dev

After this, open package.json with your code editor again, add a comma after the second last curly bracket and press the Return key to create a new line. Add the code below in this new line:

“stylelint”: {
		"extends": "stylelint-config-wordpress"
  	}

package.json should now look something like this:

{
  "name": "demo-files",
  "version": "1.0.0",
  "description": "Demo files to demonstrate implementation of the WordPress Coding Standards",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "Carme Mias",
  "license": "GPL-2.0",
  "devDependencies": {
    "eslint": "^5.8.0",
    "eslint-config-wordpress": "^2.0.0",
    "stylelint": "^9.7.1",
    "stylelint-config-wordpress": "^13.1.0"
  },
  "eslintConfig": {
    "extends": "wordpress"
  },
  "stylelint": {
    "extends": "stylelint-config-wordpress"
  }
}

Please note that the first installation step only needs to be done once, but the rest needs to be done for every project you wish to check against the WordPress Coding Standards.

You can now start using Stylelint by typing the following from the Command Line:

stylelint filename.css

The output is not as useful as that of ESLint as it doesn’t tell us if any of the errors can be automatically fixed. We can, however, run the command below to fix them:

stylelint filename.css --fix

In the example above, all the existing Coding Standard errors have been automatically fixed except one. Not bad, right?

What about HTML and Accessibility?

The WordPress Coding Standards for HTML are so brief that it is hardly worth installing a tool for them. Instead, I would encourage you to try out the online W3C Validator as recommended in the WordPress Core Developer Handbook.

As regards to Accessibility, there isn’t unfortunately a Tool yet that will assist on following the guidelines. So all we can do as things stand is follow, as best we can, the Accessibility Guidelines put together by the Make WordPress Accessibility team.

Further Reading

Here’s some useful links to find out more about some of the concepts and tools we have discussed above:

• WordPress Coding Standards.
• Squizlabs/PHP_CodeSniffer wiki.
• ESLint, ESLint on NPM and eslint-config-wordpress.
• Stylelint, Stylelint on NPM and stylelint-config-wordpress.
• W3C Validator.
• WordPress Core Developer Handbook: Accessibility Best Practices.
• Make WordPress Accessibility Guidelines.

And please get in touch with the form below if you have any comments or questions!

Enjoy !