Setting up WordPress Coding Standards (WPCS) with PHP_CodeSniffer (PHPCS) and PHP Formatting in VS Code with Remote-SSH

November 24, 2021

The Scenario:

  • You’re working in VS Code.
  • You’re working on a WordPress project on a remote *staging server (*hopefully you’re not doing this on production 😅)
  • You’d like to use PHP_CodeSniffer to lint your PHP.
  • You’d like to leverage WordPress Coding Standards (WPCS) as your PHP standard.
  • You’d like to auto-format PHP to help adhere to these standards.

1. Remote-SSH Setup

The Remote-SSH extension for VS Code allows you to SSH into a host and edit code remotely as if you were working locally. You get to see remote file and folder structure, as well as install VS Code extensions to work with your remote project.

Follow the Installation and Getting Started steps in the link above to install and activate the Remote-SSH extension in VS Code. Then connect to your remote host and change to your working directory. If you don’t already have it, install Composer before the next step.

2. Add PHP_CodeSniffer Standards Composer Installer Plugin

Open the terminal in VS Code and run composer require --dev dealerdirect/phpcodesniffer-composer-installer in your project’s root directory to install the PHP_CodeSniffer Standards Composer Installer Plugin.

3. Add WordPress Coding Standards via Composer

Next, run composer require --dev wp-coding-standards/wpcs to install the WordPress Coding Standards (WPCS) definitions and make them available in your project.

From here, you can run a command to see which coding standards are available to your local project. Example:

./vendor/bin/phpcs -i
The installed coding standards are MySource, PEAR, PSR1, PSR2, Squiz, 
Zend, PHPCompatibility, WordPress, WordPress-Core, WordPress-Docs, 
WordPress-Extra and WordPress-VIP

4. VS Code Extensions

Now we’ll install two extensions in VS Code:

phpcs – The phpcs extension by Ioannis Kappas will enable VS Code to lint our PHP in real-time while we’re working in our code. Install and activate this extension in the Remote-SSH environment:

Install extension in VS Code with Remote-SSH

phpcbf – The phpcbf extension by Per Soderlind will enable VS Code to attempt to format our code according to the standard of choice. Install and activate this extension in the Remote-SSH environment as well.

Once installed, open your command palette (Ctrl/Cmd + Shift + P) and find “Preferences: Open Remote Settings (JSON) (SSH: [yourhost])”

Within settings.json, add the following settings (replace /home/path/to/project/ with your own path):

{
  "phpcs.enable": true,
  "phpcs.executablePath": "/home/path/to/project/vendor/bin/phpcs",
  "phpcs.standard": "WordPress",
  "phpcbf.enable": true,
  "phpcbf.documentFormattingProvider": true,
  "phpcbf.onsave": true,
  "phpcbf.executablePath": "/home/path/to/project/vendor/bin/phpcbf",
  "phpcbf.standard": "WordPress",
  "editor.formatOnSave": true
}

Note: if you’re working on multiple WordPress projects within the same remote host, you may want to rerun steps 2 and 3 to install those dependencies in your user account, and update the phpcs.executablePath and phpcbf.executablePath values to point that shared location instead.

Let’s Test it Out!

Let’s see if it works! From the VS Code terminal in your Remote-SSH environment, at the root of your project enter ./vendor/bin/phpcs --report=source ./

If you have no errors or warnings, that’s great! But if you’re like me, you’ve got some issues to fix and a bunch of new work to do:

PHPCS Sniff Output
Lots of whiffs to fix!

You can try manually adding a syntax error and re-running the test to see if it catches it. Also attempt to format your PHP to auto-fix some errors. PHPCBF does a great job at fixing many things automatically.

5. PHPCS Overrides

Depending on the project, you may not want PHPCS to complain about certain errors. There are options to include code comments to ignore specific sniffs or parts of a file, but sometimes we’d prefer to have some checks skipped globally.

To accomplish this, create a phpcs.xml file in the root of your project. See below for a sample file with exclusions applied via <exclude /> tags.

<?xml version="1.0"?>
<ruleset name="My Project Rules">
    <config name="minimum_supported_wp_version" value="4.4.0" />

    <rule ref="WordPress-Core">
        <!-- Exclude these sniffs -->
        <exclude name="WordPress.WP.AlternativeFunctions" />
        <exclude name="WordPress.WP.GlobalVariablesOverride" />
        <exclude name="WordPress.DB.RestrictedClasses" />
    </rule>
    <rule ref="WordPress-Docs" />
    <rule ref="WordPress-Extra" />

    <!-- Check all PHP files in directory tree by default. -->
    <arg name="extensions" value="php" />
    <file>.</file>

    <!-- Add exclude patterns here -->
    <exclude-pattern>/tests/*</exclude-pattern>
    <exclude-pattern>/vendor/*</exclude-pattern>
</ruleset>

Bonus: Using PHPCS in CI/CD

Now that you have the PHPCS dev dependencies saved in composer.json as part of your project, you can leverage PHPCS within your CI/CD workflows to run PHP_CodeSniffer with WordPress Coding Standards and your own custom phpcs.xml overrides within your CI/CD pipeline.

Until next time! Happy (clean) coding.


Leave a comment. Let's discuss!

MichaelWritten by Michael - His career path has allowed him to incorporate his creative eye with a love of programming, analytical thinking, and learning. Michael has been married to his lovely wife Yohana since 2012. They have four wonderful children, two St. Bernard dogs, and a chinchilla. Follow @missionmikedev on Twitter