Writing better Drupal 7 code with PhpStorm and CodeSniffer

Writing standards-compliant code in Drupal 7 doesn't have to be hard! Using the power of a modern IDE, it can help to show you where you're going wrong, and ensure that all your code is standards-compliant. Here, we'll take a look at setting up JetBrains PhpStorm (our favourite IDE) to show you coding standards problems, but any IDE with CodeSniffer support will be able to do this, so it's likely Eclipse, NetBeans, and others will also help you out in the same way.

Why bother?

Good question. It's important we're all writing code in the same way, as we all come from different programming backgrounds, different cultures, and all have different ways of doing things. If we all just wrote code however we felt like writing it, when you got hold of my code, you'd have to adjust to my way of coding when you looked at my code. If you needed to make changes to it, either you'd need to adjust to my way when you wrote your code, or you'd have to introduce another style of code in the same file, making it even harder for the next person.

Besides that, having everybody write code in the same way enhances the stability of the code and makes it less error-prone. You spend less time thinking about how the code is structured, since it's always the same, and you spend more time thinking about how the code actually works.

Prerequisites

Do bear in mind this is based on a Linux installation, but OSX and Windows both have PEAR available and both operate in the same way, so apart from minor path differences, this will work just fine.

Oh great, I have to install a bunch of crap first? Yes, fraid so. Luckily this is pretty painless. There's a number of ways to get PHP_CodeSniffer installed but we prefer the PEAR method. Just type pear install PHP_CodeSniffer at your friendly command line prompt. That's pretty much it. CodeSniffer's installed.

Next, you'll need the Drupal-specific coding standards in a format that CodeSniffer can understand. Luckily, the coder module provides these standards, so grab a copy of that. Note that you don't need to install or use the coder module on your site; it just contains the standards inside it.

Inside the archive you download, you'll find there's a coder_sniffer/Drupal subdirectory. You want to extract this subdirectory and move (or symlink) this to /usr/share/php/PHP/CodeSniffer/Standards/Drupal. This will vary based on your Linux distro or operating system, but this is generally the place where PEAR decides to install stuff. If you end up with a file at /usr/share/php/PHP/CodeSniffer/Standards/Drupal/ruleset.xml (or your equivalent path) and a bunch of subdirectories, you're good to go.

PhpStorm setup

Head to your PhpStorm settings and type 'sniff' into the search box. You will need to point PhpStorm to your CodeSniffer path. On Linux, this is just going to be /usr/bin/phpcs but on Windows, it will be different, and you're looking for phpcs.bat instead. Make sure you click 'validate' on this screen to get a confirmation that PhpStorm and CodeSniffer can talk to each other.

Now you've done that, head to your project and configure its inspections. A quick way of doing that is clicking the little icon that looks like a guy in a top hat in the bottom right of the main window. No, seriously, it's a guy in a top hat, I'm telling you!

In the inspections for PHP, turn on CodeSniffer validation, and then click on this particular validator. You'll notice a little drop-down with a selection of coding standards to use. Pick 'Drupal' from the list (you might need to hit the little refresh icon next to it first, otherwise Drupal might not appear). By default, the level of the warning is weak warning, but change this to warning. If things are weak warnings, you'll end up disregarding them altogether, and coding standards violations, while they won't stop your module from working, should be treated as things to fix right away while writing code.

Now, whenever you open a file in your project, you'll be presented with a whole load of warnings (unless you already write gleaming, standards-compliant code). Not that I'm picking on the bean module, because it's great, but it was the first one I had to hand that wasn't perfect. Here's what you'll see:

There's a few issues with the code here, but none are difficult to solve!

Clean margins!

What I mean by this is that the right margin shows a yellow or red stripe mark in PhpStorm whenever a line contains a warning or error. Internally, we operate a "clean margins" policy, which means that these stripes must be removed before committing any code. Weak warnings, such as unused variables, are acceptable (since you don't always use all the parameters in the function when you implement a hook, for example).

This is not an excuse to make everyone do a huge amount of extra work! Instead, what we find is that people's attitudes and styles change over time, while using CodeSniffer, and pretty soon, we're actually writing standards-compliant code first time, rather than having to go back through line by line and clean up.

YMMV

This is a specific example on how to set up PhpStorm and PHP_CodeSniffer to help with coding standards, and specifically on Linux, but if you have any experience using other IDEs where this is a possibility, or you operate things a little differently, we'd love to hear from you in the comments.