Squiz Labs Blog - The latest news from the R&D division of Squiz®

Subscribe to our RSS feeds

Closure Linter Support in PHP_CodeSniffer

Last week, Google announced that they had open sourced a new tool, Closure Linter, to enforce their JavaScript style guide. Closure Linter checks for a range of common JS and Google style errors and includes some checking in there for JSDoc comments as well.

The timing couldn't have been much better as we were just discussing the need for new Squiz sniffs to enforce JsDoc comments for our JavaScript files. Re-writing the comment parser in PHP_CodeSniffer to support the different tags and syntax that JsDoc uses was not something easily achievable. So instead, we have added a new sniff that runs Closure Linter on each JS file and reports errors and warnings through PHP_CodeSniffer.

The output looks a bit like this:

  17 | WARNING | gjslint says: (0200) Invalid JsDoc tag: package
  18 | WARNING | gjslint says: (0200) Invalid JsDoc tag: subpackage
  20 | WARNING | gjslint says: (0200) Invalid JsDoc tag: copyright
  22 | WARNING | gjslint says: (0225) Missing @this JsDoc in function
     |         | referencing "this". (this usually means you are
     |         | trying to reference "this" in a static function, or
     |         | you have forgotten to mark a constructor with
     |         | @constructor)
  24 | ERROR   | Missing docs for parameter: "id"
  24 | ERROR   | Missing docs for parameter: "screenid"
  24 | ERROR   | Missing docs for parameter: "system"
 114 | ERROR   | Additional whitespace found at end of file

By default, all errors produced by Closure Linter are added as warnings and start with gjslint says so you can easily ignore these if they are incorrect. You'll also notice that the warning messages include the error code in brackets, as well as the message. This error code is the internal code used by Closure Linter and has nothing to do with PHP_CodeSniffer itself, although you can use it to customise your own standard. You can view a full list of the error codes, along with a very basic description of each, in the errors.py source file.

This new generic sniff was designed to allow for flexible customisation. You can specify a list of Closure Linter error codes to both completely ignore and report as errors instead of warnings. For the Squiz coding standard, we ignore some warnings that conflict with our own standards and have some JsDoc-based warnings reported as errors. We also change the format of those important messages to remove the gjslint says prefix so they fit in more easily with the other errors being reported.

All this is done easily using the new ruleset.xml format in PHP_CodeSniffer 1.3.0. This snippet comes from the ruleset.xml file for the Squiz standard and has been committed to the PHP_CodeSniffer SVN repository, along with the new ClosureLinter sniff to do the work.

<!-- We don't want gsjlint throwing errors for things we already check -->
<rule ref="Generic.Debug.ClosureLinter">
  <property name="errorCodes" type="array" value="0210"/>
  <property name="ignoreCodes" type="array" value="0001,0110,0240"/>
<rule ref="Generic.Debug.ClosureLinter.ExternalToolError">

Installing Closure Linter is pretty easy (install guide here). Once installed, you'll have a new gjslint command available to you. To tell PHP_CodeSniffer where gjslint is installed, run the following command:

phpcs --config-set gjslint_path /path/to/gjslint

Note that you will need to install PHP_CodeSniffer from the latest SVN checkout for this to work and the Squiz standard is the only current standard to use this new sniff. To check a JavaScript file using the Squiz standard, run the following command:

phpcs --standard=Squiz /path/to/file.js

This new sniff is another great reason to plan your migration to PHP_CodeSniffer 1.3.0 (currently in beta) including the conversion of any custom standards to the new ruleset.xml format. Please read the custom coding standard upgrade guide for more information.

Squiz Labs

R & D division of Squiz Pty Ltd

Open source web experience management solutions

Squiz Labs is the research and development division of Squiz, the company behind the Squiz Suite of web experience management and development tools.

Our PHP and JavaScript developers are responsible for producing innovative enterprise-quality software while our interface designers and testing team ensure our products both look great and are easy to use.