Using WordPress Coding Standards for PHP_CodeSniffer in Your Plugin or Theme

Ensuring that your WordPress plugin or theme adheres to the WordPress Coding Standards is crucial for maintaining high-quality, readable, and maintainable code. PHP_CodeSniffer (PHPCS) is a powerful tool that helps you automate this process. In this article, I will guide you through setting up PHP_CodeSniffer with WordPress Coding Standards using Composer.

1. Initialize Composer in Your Plugin or Theme

Before configuring Composer with the required packages, you need to initialize it in your plugin or theme directory. This will create a composer.json file, which will manage your project’s dependencies.

  • Navigate to your plugin or theme directory.
  • Initialize Composer composer init
  • Follow the prompts to set up your composer.json file

2. Configure Composer

With Composer initialized, you need to configure it to use the WordPress Coding Standards.

A. Allow Composer plugins

composer config allow-plugins.dealerdirect/phpcodesniffer-composer-installer true

B. Require the WordPress Coding Standards package

composer require --dev wp-coding-standards/wpcs:"^3.0"

Now, your composer.json file should look something like this:

{
    "name": "youssefbouhlal/test-phpcs",
    "type": "wordpress-plugin",
    "license": "GPL-3.0+",
    "config": {
        "allow-plugins": {
            "dealerdirect/phpcodesniffer-composer-installer": true
        }
    },
    "require-dev": {
        "wp-coding-standards/wpcs": "^3.0"
    }
}

3. Add phpcs.xml File

Next, create a phpcs.xml file in the root directory of your plugin or theme. This file tells PHP_CodeSniffer which coding standards to use and which files and directories to scan. Here is an example configuration:

<?xml version="1.0"?>
<ruleset name="WordPress Coding Standards">

    <!-- tells phpcs to use the WordPress coding standard. -->
    <rule ref="WordPress"></rule>

    <!-- basepath is set to the current directory. -->
	<arg name="basepath" value="."/>

    <!-- specifies that all files in the current directory will be checked. -->
    <file>.</file>

    <!-- exclude folders -->
    <exclude-pattern>*/node_modules/*</exclude-pattern>
	<exclude-pattern>*/vendor/*</exclude-pattern>
	<exclude-pattern type="relative">build/*</exclude-pattern>
	<exclude-pattern type="relative">asssets/*</exclude-pattern>

</ruleset>

4. Run with npm

If your project uses npm, you can run PHP_CodeSniffer via npm scripts. First, add lint:php to your project’s package.json scripts:

"scripts": {
    "lint:php": "vendor/bin/phpcs"
}

Then, you can run the linter using npm:

npm run lint:php

5. Run with Composer

Alternatively, you can run PHP_CodeSniffer using Composer scripts. Add the following to your composer.json file:

"scripts": {
    "lint:php": "vendor/bin/phpcs",
}

Run the linter with Composer:

composer lint:php

6. Example Output

When you run PHP_CodeSniffer, you will see output in the terminal that looks something like this:

> vendor/bin/phpcs

FILE: test-phpcs.php
----------------------------------------------------------------------------
FOUND 4 ERRORS AFFECTING 4 LINES
----------------------------------------------------------------------------
  1 | ERROR | [ ] Missing file doc comment
  4 | ERROR | [x] There must be no blank lines after the function comment
  8 | ERROR | [x] Tabs must be used to indent lines; spaces are not allowed
 10 | ERROR | [x] Tabs must be used to indent lines; spaces are not allowed
----------------------------------------------------------------------------
PHPCBF CAN FIX THE 3 MARKED SNIFF VIOLATIONS AUTOMATICALLY
----------------------------------------------------------------------------
#