Syntax Checking for Drupal in VIM

Jan 10 2012

Vim (VI Improved) is a powerful text editor that comes standard on most versions of Linux, OS X, BSD, and other UNIXes. With thousands of add-ons, console and GUI versions, and a fully scriptable environment, you can transform a humble text editor into a powerful development tool. In fact, there are several Drupal add-ons for vim.

In this article, I explain how to turn on syntax checking for PHP, adding code style validation along with error checking. We do this with three tools: The Syntastic Vim plugin, the PHP CodeSniffer PEAR package, and the Drupal Code Sniffer project from Drupal.org. <!--break-->

Syntastic

The first thing to do is add a Vim module that provides generic syntax checking for programming languages. The syntastic Vim plugin includes support for a few dozen languages out of the box, including PHP, CSS, Ruby, (X)HTML, and several other common web-oriented languages.

The installation instructions for Syntastic suggest using another Vim plugin (pathogen) to install Syntastic. I use the Janus Vim bundle, which comes with Syntastic.

PHP CodeSniffer

Once Syntastic is installed and working, we can extend it a little. Syntastic uses the php command to perform error checking, but it can also perform code style checks as well, giving you an inline warning when your code does not conform to convention.

To gain this extra level of support, we need the PHP CodeSniffer, which provides the commandline client phpcs. This can be installed easily using PHP's pear package manager:

$ pear install PHP_CodeSniffer

(You may need to execute the above with sudo or as the root user.)

Once this is installed, you should have a program called phpcs available on the commandline. You can test it on a PHP file by running phpcs foo.php, where foo.php is some existing PHP file.

By default, PHP CodeSniffer enforces a particular coding standard: The PEAR standard. This is not the same coding standard that Drupal uses. In fact, since PEAR requires a 4-space indent, chances are that it will give you a LOT of warnings.

What we need are Drupal-specific code sniffing rules. And those will come from a different package.

The Drupal Code Sniffer

The Drupal Code Sniffer is a package maintained at Drupal.org. It provides grammars and syntaxes for PHP Code Sniffer.

To install it, you can either download the project snapshot or retrieve it from Drupal's Git repository.

$ git clone drupal://drupalcs

You will then need to follow the instructions on the project page to install DrupalCS. In most cases, this merely requires creating a symbolic link or moving a directory.

Note One installation suggestion is to use a Bash alias for phpcs. This will not work with Syntastic and Vim without some extra legwork on your part. I suggest sticking with the standard installation instructions.

Once you are done, you can test whether phpcs can see your new format:

phpcs -i
The installed coding standards are DrupalCodingStandard, MySource, PEAR, PHPCS, Squiz and Zend

If DrupalCodingStandard is missing from the list above, you have not successfully installed the DrupalCS package.

Editing Your .vimrc (or .vimrc.local)

The last thing to do is tell Vim and Syntastic about your preferred syntax. The easiest way to do this is to add the following line in the file called .vimrc (note the leading dot). This should be in your home directory.

$ echo "let g:syntastic_phpcs_conf='--standard=DrupalCodingStandard'" >> ~/.vimrc

The above will add the following line to the end of your .vimrc:

let g:syntastic_phpcs_conf="--standard=DrupalCodingStandard"

From that point on, anytime you edit a file, VIM will be able to check your code formatting against the Drupal coding standards.

Working with Syntastic

There are many options available with Syntastic. To get to know them, you can execute :h syntastic inside of Vim. This will show syntastic's built-in help. Janus, the bundle of Vim plugins that I use, automatically configured Syntastic to run each time the file is saved. But by default you must manually execute syntastic. Here are a few commands that will come in helpful:

:SyntasticCheck

This causes Syntastic to check the file and report any errors. As I have Syntastic configured, it will flag each line with a left-marginal red box for an error, and a yellow box for a warnings.

:Errors

To see the verbose error report from Syntastic, you can execute :Errors. In the screenshot above, you can see the error pane at the bottom of the window. For each error, it prints out the file (not shown), the line and character numbers, and the message.

To close the error console, switch to that pane (CTRL-W, CTRL-W) and close it (:q).

For most practical cases, that's really all there is to it.

Syntax errors are nice, but code formatting errors are SO ANNOYING. How do I turn it off?

As we have it configured, two checks are run on your code:

  • PHP itself is used to check for syntax errors (php -l).
  • PHP CS is used to check your code style.

But the code style "errors" are not compilation errors, but merely violations of some coding standard's formatting guidelines. As helpful as this can be at times, it can also be a nusance sometimes.

Want to disable format checking? There's a flag for that:

let g:syntastic_phpcs_disable=1

The flag above disables the format checking for phpcs, but leaves the PHP syntax checking on. So you will only get real syntax errors. Not formatting errors.

Customizing PHPCS Output

Want to tune and tweak the output of phpcs? The best way to do this is to test it by hand, running phpcs and testing out various options and flags.

The command phpcs --help will print out a detailed list of available options.

Updated: Ryan Johnston's fixes have been incorporated.