A Cloud9 plugin for applying WordPress Coding Standards using PHP CodeSniffer

The WP Captain team loves Cloud9 IDE and is using it for anything related to WordPress development. In this post, we’ll share with you a Cloud9 plugin we’ve developed that you can use to enable an analyzer in the editor that will show you which part of your code doesn’t comply with WordPress Coding Standards.

Cloud9 Editor

Introduction

First things first. Before getting started with our plugin, let’s talk quickly about Cloud9 IDE, WordPress Coding Standards and PHP CodeSniffer. If you already know about them, skip these parts by clicking here.

About Cloud9

Chances are that if you’re here, you know what Cloud9 is. But for those who’ve never heard of Cloud9, it was previously called Cloud9 IDE until it has been acquired by AWS. Here’s a quick summary of what it can do:

AWS Cloud9 is a cloud-based integrated development environment (IDE) that lets you write, run, and debug your code with just a browser. It includes a code editor, debugger, and terminal. Cloud9 comes prepackaged with essential tools for popular programming languages, including JavaScript, Python, PHP, and more, so you don’t need to install files or configure your development machine to start new projects. Since your Cloud9 IDE is cloud-based, you can work on your projects from your office, home, or anywhere using an internet-connected machine.

You can read more about it and get started with AWS Cloud9 here. Also, even if you’ve never heard of Cloud9 before, you’ve probably heard of Ace, which is an open-source code editor bundled with Cloud9 IDE and actively maintained by the Cloud9 IDE and Mozilla teams. You can read more about Ace here.

About WordPress Coding Standards

Again, if you’re reading this post, it means you’re a WordPress developer, in which case you should already know about WordPress Coding Standards. But just in case you don’t:

The purpose of the WordPress Coding Standards is to create a baseline for collaboration and review within various aspects of the WordPress open source project and community, from core code to themes to plugins. Coding standards help avoid common coding errors, improve the readability of code, and simplify modification. […] Following the standards means anyone will be able to understand a section of code and modify it, if needed, without regard to when it was written or by whom.

If WordPress Coding Standards (WPCS) are a new thing for you, you should know that WPCS are available for CSS, HTML, JS and PHP. I highly recommend that you start by reading the Best Practices chapter of the Core Contributor Handbook on Make WordPress, especially the part regarding PHP Coding Standards and PHP Documentation Standards.

About PHP CodeSniffer

PHP CodeSniffer (PHPCS) is a tool used to automate the process of validating a piece of code based on selected standards:

PHP_CodeSniffer is a set of two PHP scripts […] [used] to detect violations of a defined coding standard, and […] to automatically correct coding standard violations. PHP_CodeSniffer is an essential development tool that ensures your code remains clean and consistent.

PHPCS can’t validate code without a set of rules (also called sniffs). For example, sniffs exist for validating code against a specific version of PHP, and a set of rules even exists for validating code developed especially for WordPress.
PHPCS is normally used directly from the Terminal, but our plugin for Cloud9 will make things easier for you by displaying coding errors and warnings directly in your code editor.


WordPress Coding Standards Analyzer for Cloud9 IDE

This Cloud9 package provides a code analyzer and validator for WordPress development in Cloud9 ID9. It uses PHP CodeSniffer (PHPCS) along with WordPress Coding Standards (WPCS) and PHPCompatibility/PHPCompabitityWP rule sets. You don’t have to install anything else than this plugin on your Cloud9 workspace, as it comes packaged with the latest version of PHPCS, WPCS and PHPCompatibility rules.

Installation

  1. From the Cloud9 menu, select Preferences, then Experimental -> SDK and enable the Plugin Manager. Click here for more details about Cloud9 Experimental Features.
  2. Open a Terminal from the menu Window -> New Terminal.
  3. Run these commands in the terminal for each project where you want to use the plugin:
    git clone [email protected]:EP4/c9.ide.language.php.wordpress.git
    cd c9.ide.language.php.wordpress
    c9 install .
    cd ..
    rm -fR c9.ide.language.php.wordpress
    
  4. If you don’t want to activate the plugin manually every time you open your Cloud9 project, you can enable it automatically. Click on the Cloud9 menu, select Open Your Init Script and add the following code:
    services.pluginManager.loadPackage([
    	"~/.c9/plugins/c9.ide.language.php.wordpress/package.json"
    ])
  5. Restart Cloud9.
  6. Use Cloud9 as usual, and warnings will be displayed in the IDE when working on PHP files if PHP CodeSniffer detects any error based on PHPCompatibilityWP & WordPress Coding Standards rules.

Usage

This plugin will display errors found by PHPCS directly in the IDE, as you can see on the following screenshots:

This plugin will do the following

  • check_box Run PHPCS on the current PHP file using WordPress Coding Standards and PHPCompatibility rules.
  • check_box If errors are found, a warning icon will be displayed next to the line number.
  • check_box When hovering that icon, a tooltip with a message explaining the error(s) will be displayed.
  • check_box In the message, icons will be displayed for helping you distinguish if this is a warning or an error, and if it can be fixed automatically by PHPCBF.
  • check_box In the message, the line and column where the error can be found in the code will be displayed inside parentheses.
  • check_box In the code, errors will be underlined with a red dotted line, and highlighted in red so you can rapidly identify them. Please note that the highlighted characters might not actually be accurate.

This plugin won’t do the following (yet)

  • check_box_outline_blank Run PHPCBF and fix issues automatically. You’ll have to run PHPCBF from the Terminal, or fix issues manually based on the recommendations given.
  • check_box_outline_blank Allow the user to enable or disable specific standards and rules. You’ll need to manually edit the settings of the plugin in the phpcs_handler.js file which can be found in the worker directory.
  • check_box_outline_blank Update itself automatically. At the moment, all rules must be updated manually. I’ll update this plugin once in a while with the most recent rules available.

Icons used in messages

Since there is no simple way to allow HTML in these tooltips, we use some custom Unicode characters for displaying more meaningful messages:

Displayed Characters Meaning
🔴 Red Circle The identified issue is considered to be an error by PHPCS.
 
🔶 Yellow Diamond The identified issue is considered to be a warning by PHPCS.
 
✔ Checkmark The issue can be resolved automatically by running PHPCBF.
 
𝗪𝗣𝗖𝗦 The issue was identified using WordPress Coding Standards Rules.
 
𝗣𝗛𝗣𝗖𝗼𝗺𝗽𝗮𝘁𝗶𝗯𝗶𝗹𝗶𝘁𝘆 The issue was identified using PHPCompatibility Rules.
 
➀ to ➈ Any number displayed in a circle represent the severity level of the issue. ➄ is the default severity and is never displayed.
 
(𝟏𝟐𝟑:𝟕𝟖𝟗) Numbers displayed inside parentheses refer to the line and column where the issue can be found. In this example, look at line 123 and column 789.

Resources

Changelog

1.0.1 – 2018-10-11

  • Removing the tab-width=0 parameter since the tab-width is already set by WordPress rules and it was now triggering false positives.
  • Fixing some typos in the README.md file.

1.0.0 – 2018-10-10

  • Updating PHP_CodeSniffer library to version 3.3.2.
  • Updating WordPress Coding Standards to version 1.1.0.
  • Updating PHPCompabitity standards to version 9.0.0.
  • Adding PHPCompabitityWP 2.0.0 and PHPCompatibilityParagonie 1.0.0 standards.
  • Increasing the stdout max output from 200KB to 500KB.
  • Increasing the timeout from 5 to 10 seconds.
  • Moving the checkmark icon (✔) after the position in the tooltip.
  • Including license files for each coding standards.
  • Removing the CSS rule used for hiding the debug bar since the plugin can be used without activating the debug mode now.
  • Some code refactoring.
  • Updating the ‘Installation’ section of the docs.

0.0.2a – 2017-02-13

  • Updating WordPress Coding Standards with the latest release as of 2017-02-10.
  • Updating PHPCompabitity standards with the latest release as of 2017-02-06

0.0.1 (alpha) – 2017-02-10

Initial release.

Leave a comment

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Dave Lavoie
Co-Founder of WP Captain, I'm a senior WordPress developer and solutions architect. I lead all WordPress development efforts and provide advanced customer support to our users.

We keep your WordPress sites running nicely

Hosting, maintenance & security solutions by experienced WordPress DevOps.