Monday, May 2, 2022

PHP Code Sniffing & Formatting in VSCode

While coding, it is very important to follow specific coding standards and format the code to make it easy to read. It is one of the fundamentals of coding and is applied to every programming language. Here I am going to show you how you can follow coding standards with PHP and format the code.

While coding in PHP using VSCode, there are plenty of extensions that provide code formatting. Some of those are PHP Intelephense, phpfmt, and PHP Formatter. These are good extensions but don’t provide a better solution for code sniffing and formating code using PHP Standards. To gain more knowledge on PHP Coding Standards (also called PSR), please check PHP-FIG website.

PHP_CodeSniffer

PHP_CodeSniffer is a set of tools that allows linting and formatting of code in one package and it’s an independent tool. You can simply use it as a set of simple commands on the terminal. The linting tool provided is called phpcs and the formatting tool provided is called phpcbf.

You will need composer to install PHP_CodeSniffer on your system. Please follow the steps mentioned in the original GitHub repo for it.

After you install PHP_CodeSniffer, please note down the path of its installation location.

On Linux or Mac OS, it will be like the below:

./vendor/bin/phpcs
./vendor/bin/phpcbf

On Windows, it will be like this.

C:\Users\YOUR_USERNAME\AppData\Roaming\Composer\vendor\bin\phpcs.bat
C:\Users\YOUR_USERNAME\AppData\Roaming\Composer\vendor\bin\phpcbf.bat

Once installed, make sure it is working properly by running test commands like this.

phpcs --version
phpcbf --version

WordPress Coding Standards

While doing WordPress theme development or plugin development, it is very important to follow its own set of rules and coding standards. WPCS (WordPress Coding Standards) is most commonly used for that. It adds a set of rules in phpcs and phpcbf utilities so that it can check and format the code based on WordPress coding conventions. So it is important that you already have installed PHP_Codesniffer on your system.

To install WPCS, follow the steps below:

1. Clone the WordPress standards repository

 git clone -b master https://github.com/WordPress/WordPress-Coding-Standards.git wpcs

2. Add its path to the PHP_CodeSniffer configuration

phpcs --config-set installed_paths /path/to/wpcs

3. Test if the WordPress standards are configured properly or not by running the below command.

phpcs -i

It should show a list of coding standards followed by a comma. You will see entries like WordPress, WordPress-Core, etc in it.

WPVIP Coding Standards

If you want to install WPVIP Coding Standards which I highly recommend, run the below command and it should work straight away.

Ref: https://docs.wpvip.com/how-tos/php_codesniffer/#h-install-globally

composer g require --dev automattic/vipwpcs dealerdirect/phpcodesniffer-composer-installer -W

Visual Studio Code

To use the 2 utilities with VSCode, we will need two extensions with similar names.

phpcs
phpcbf

Follow the links and install the extensions. Once installed, open VS Code User Settings JSON file and add the below entries to it. Make sure if some of these entries are already there then delete them.

For Windows OS :

"php.validate.run": "onSave",
"phpcs.enable": true,
"phpcbf.enable": true,
"phpcs.executablePath": "C:\\Users\\YOUR_USERNAME\\AppData\\Roaming\\Composer\\vendor\\bin\\phpcs.bat",
"phpcbf.executablePath": "C:\\Users\\YOUR_USERNAME\\AppData\\Roaming\\Composer\\vendor\\bin\\phpcbf.bat",
"phpcs.standard": "PSR12", //WordPress
"phpcbf.standard": "PSR12", //WordPress
"phpcbf.documentFormattingProvider": true,
"[php]": {
	"editor.tabSize": 4,
	"editor.defaultFormatter": "persoderlind.vscode-phpcbf"
},

For Linux/Mac OS :

"php.validate.run": "onSave",
"phpcs.enable": true,
"phpcbf.enable": true,
"phpcs.executablePath": "/home/YOUR_USERNAME/.config/composer/vendor/bin/phpcs",
"phpcbf.executablePath": "/home/YOUR_USERNAME/.config/composer/vendor/bin/phpcbf",
"phpcs.standard": "PSR12", //WordPress
"phpcbf.standard": "PSR12", //WordPress
"phpcbf.documentFormattingProvider": true,
"[php]": {
	"editor.tabSize": 4,
	"editor.defaultFormatter": "persoderlind.vscode-phpcbf"
}

Make sure the Paths for executablePath are correct otherwise it will not work. Also, notice the phpcs.standard and phpcbf.standard settings. These must be the same. If you are working on any normal PHP project, use PSR12 and if you are working on any WordPress project, use WordPress standard.

Once these settings are added, restart your VS Code, open any PHP file and check if it’s showing those red lines for linting errors. If you see them then we are done. 🙂

Try making changes to the PHP file and save it, the code should auto format & fix after saving the file.

I hope you find this useful. Thank You.

Update 30-06-2022: Recently I found a nice VSCode extension for code sniffing purpose, called PHP Sniffer. It integrates very easily with VSCode and there are very less configurations. Copy them from below if you are interested:

// For WSL or Linux
{
	"phpSniffer.standard": "WordPress",
	"phpSniffer.executablesFolder": "/home/aslam/.config/composer/vendor/bin/", //PSR12
	"[php]": {
		"editor.tabSize": 4,
		"editor.defaultFormatter": "wongjn.php-sniffer"
	}
}


// For Windows
{
	"phpSniffer.standard": "WordPress",
	"phpSniffer.executablesFolder": "C:\\Users\\welan\\AppData\\Roaming\\Composer\\vendor\\bin\\", //PSR12
	"[php]": {
		"editor.tabSize": 4,
		"editor.defaultFormatter": "wongjn.php-sniffer"
	},
}