Setting WordPress Coding Standards per project using Composer
Tags: php, linting, wordpress, phpcs
Published: 2023-07-04 14:44:21

[PHP CodeSniffer](https://github.com/squizlabs/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](https://github.com/WordPress/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](https://github.com/WordPress/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](https://www.php.net/)
- [Composer](https://getcomposer.org/)
- [VS Code](https://code.visualstudio.com/) 
- [phpcs extension](https://marketplace.visualstudio.com/items?itemName=shevaua.phpcs)

## 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](https://marketplace.visualstudio.com/items?itemName=shevaua.phpcs). 

### Extension Settings

According to the [phpcs](https://marketplace.visualstudio.com/items?itemName=shevaua.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.