Setting WordPress Coding Standards per project using Composer

PHP CodeSniffer is an essential development tool that ensures our code to remains clean and consistent. Works with two PHP scripts, the phpcs which tokenizes PHP, JavaScript, and CSS files to detect violations, and the phpcbf which automatically corrects coding standard violations.

It helps us to achieve uniformity of code styles and we also can add our "preferred" standards, like the WordPress Coding standards (subject of this article), or even some customized standards defined by your team/employer.

There are several ways to config that, but I will manage WordPress Coding Standards through Composer so we can share these standards per project. I also will cover the steps to config this in my IDE, VS Code.

These steps can also be used to handle any other standard packages you prefer. Just make the appropriate substitutions from WordPress Coding Standards to your code standard.

Requirements

(I am assuming you have a understanding about PHP and Composer).

• PHP
• Composer
• VS Code
• phpcs extension

Installing Standards

We need to install PHP Code Sniffer and WordPress Coding Standards, for that run the following commands on your project folder:

composer require --dev squizlabs/php_codesniffer

composer require --dev wp-coding-standards/wpcs

If you prefer, can edit directly your composer.json file adding these lines:

"require-dev": {
    "squizlabs/php_codesniffer": "^3.7",
    "wp-coding-standards/wpcs": "^2.3",
}

The files will be added to your vendor folder, including wpcs. If you choose to update your composer.json file directly, remember to run composer update.

To check if worked, run ./vendor/bin/phpcs -i to see the standards

The first time, the expected output will be

The installed coding standards are MySource, PEAR, PSR1, PSR2, PSR12, Squiz and Zend

Tell PHP Code Sniffer about our custom standards

To use WPCS (or other customized standards), we have to tell the PHP Code Sniffer about the WordPress Coding Standards. For that run the command:

./vendor/bin/phpcs --config-set installed_paths vendor/wp-coding-standards/wpcs

To confirm it worked, run ./vendor/bin/phpcs -i again and the expected output this time should be:

The installed coding standards are MySource, PEAR, PSR1, PSR2, PSR12, Squiz, Zend, WordPress, WordPress-Core, WordPress-Docs, and WordPress-Extra

Scripts

I added some scripts to my project composer.json to help me with these commands (they will be useful later in creating a phpcs workflow using GitHub actions, but that's a subject for another article).

 "scripts": {
    "cs-packages": "./vendor/bin/phpcs -i",
    "cstd": "./vendor/bin/phpcs --config-set installed_paths vendor/wp-coding-standards/wpcs",
    "cs": "./vendor/bin/phpcs --standard="WordPress" --report=summary .",
    "cbf": "./vendor/bin/phpcbf --standard="WordPress ."
  },

VS Code extension

For VS Code "to understand the standards", we need some extension, my chosen one was the phpcs.

Extension Settings

According to the phpcs extension documentation, was created this settings.json on the .vscode folder of the project (so we can add to git and easily transport or manage versions). For other IDEs or extensions, change you will have to change the settings.json accordingly.

{
    "phpcs.enable": true,
    "phpcs.lintOnSave": true,
    "phpcs.showSources": false,
    "phpcs.standard": "WordPress",
    "phpcs.ignorePatterns": [
        "*/vendor/*"
    ],
}

Usage

If you installed everything correctly because the "phpcs.lintOnSave": true, line on settings.json, on save, any PHP file is working will be linted correctly and the errors will be displayed on problems. We can also run the following commands on the terminal to check a single file:

./vendor/bin/phpcbf --standard="WordPress" /file-name.php

To display a report on the terminal:

./vendor/bin/phpcs --standard="WordPress" /file-name.php

We can also run the commands to check all the files at once in the project but may experience performance issues depending on your project size, use it carefully, in some cases May be necessaire to adjust our php.ini directives like max_execution_time.

./vendor/bin/phpcbf --standard="WordPress" .

To display a report on the terminal:

./vendor/bin/phpcs --standard="WordPress" .

Soon, I will write about my phpcs.yml GitHub actions workflow, using this composer.json, for automatically linting my project on push to a directory.