Syntax Checking for Drupal in VIM
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.
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.
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
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
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
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:
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.
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 (
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 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:
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
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
phpcs --help will print out a detailed list of available
Updated: Ryan Johnston's fixes have been incorporated.