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

PHP_CodeSniffer 1.3.0RC1 released

PHP_CodeSniffer version 1.3.0 release candidate 1 has just been uploaded to PEAR and is now available to install. This release has been focused on bug fixing and general stabilising of the architectural changes released in 1.3.0a1, but there were also a few nice features that made it in.  Some of the highlights in this release are:

• Support for exclude-pattern tags in ruleset.xml files
  
• A new --encoding command line argument to fix UTF-8 encoding issues in some reports
  
• All reported bugs are now fixed

New features have been documented and will be available on the PHP_CodeSniffer documentation page once the documentation regenerates over the weekend. This includes an updated coding standard tutorial and an annotated ruleset.xml file to take you through all the features of this new format and how to use them.

Developers who have built custom coding standards are encouraged to read the 1.3.0 upgrade guide to ensure your standards are ready for the 1.3.0 stable release. No release date is set, but it's a fairly easy upgrade process and doing it early will give you plenty of time for testing.

You can view the full changelog on the PHP_CodeSniffer download page.

Upgrading custom coding standards to support version 1.3.0

PHP_CodeSniffer version 1.3.0 is currently in alpha, but it contains an important backwards compatibility break that all coding standard authors need to be aware of. Upgrading your coding standard to make use of the new ruleset.xml files is an easy process and this guide will show you how to get it done.

Please note that if you have not created your own coding standard, you do not need to follow this guide. Users of PHP_CodeSniffer that use one of the built-in standards can continue to check their code as normal.

This guide assumes your coding standard has the following directory structure, which is based off the coding standard tutorial in the PHP_CodeSniffer documentation:

MyStandard
|_ MyStandardCodingStandard.php
|_ Sniffs
   |_ Commenting
      |_ DisallowHashCommentsSniff.php

In this sample coding standard, we have a single sniff being included directly within the standard's sniff directory. But it doesn't matter how many sniffs you have as they are automatically included into the standard in all versions of PHP_CodeSniffer. Your standard may not even have any directly included sniffs, preferring to include sniffs from other standards via the CodingStandard.php class.

So the only thing we need to do to upgrade a custom coding standard is convert the CodingStandard.php class to a ruleset.xml file. We can leave all directly included sniffs alone and we don't have to change our directory structure.

The Basics

The first thing you need to do is create a ruleset.xml file directly under your top-level directory. The name of the file must be ruleset.xml

touch MyStandard/ruleset.xml

The contents of this file will be minimal if you are not including any sniffs from other standards. So the file content would look like this:

<?xml version="1.0"?>
<ruleset name="My Standard">
 <description>My custom coding standard</description>
</ruleset>

A simple ruleset.xml file like this tells PHP_CodeSniffer that this directory contains a coding standard, the name of the standard is My Standard and the sniffs in the standard are sourced directly from the default Sniffs directory.

Once you've created your ruleset.xml file, you can go ahead and delete the CodingStandard.php class file as it is no longer required. However, you can keep both files in the coding standard if you want to use your standard in both old and new versions of PHP_CodeSniffer. But be aware that you will need to make changes to both files and any advanced ruleset features you add to your ruleset.xml file can not be replicated in your CodingStandard.php class file.

A Simple Coding Standard Class

You can build on a coding standard by including sniffs from other standards. A sample CodingStandard.php class from the PHP_CodeSniffer documentation contains this:

public function getIncludedSniffs()
{
  return array(
          'PEAR',
          'Generic/Sniffs/Formatting/MultipleStatementAlignmentSniff.php',
          'Generic/Sniffs/Functions',
         );

}//end getIncludedSniffs()

The example above includes the MultipleStatementAlignment sniff from the Generic coding standard, all sniffs in the Functions category of the Generic coding standard and all sniffs defined in the PEAR coding standard.

These rules would be replicated in a ruleset.xml file like this:

<?xml version="1.0"?>
 <ruleset name="My Standard">
 <description>My custom coding standard</description>
 <rule ref="PEAR"/>
 <rule ref="Generic.Formatting.MultipleStatementAlignment"/>
 <rule ref="Generic/Sniffs/Functions"/>
</ruleset>

The two changes here are the use of the rule tag to include sniffs and standards and also the way we reference an individual sniff. Instead of specifying the path to the sniff we instead specify the internal code that PHP_CodeSniffer gives it, which is based on the path. It's actually a pretty easy conversion. Just just drop the Sniffs directory, convert the slashes to periods and remove Sniff.php from the end. Here are some more examples to make sure it is clear.

BEFORE: Generic/Sniffs/VersionControl/SubversionPropertiesSniff.php
AFTER:  Generic.VersionControl.SubversionProperties

BEFORE: PEAR/Sniffs/ControlStructures/ControlSignatureSniff.php
AFTER:  PEAR.ControlStructures.ControlSignature

BEFORE: Squiz/Sniffs/Strings/DoubleQuoteUsageSniff.php
AFTER:  Squiz.Strings.DoubleQuoteUsage

Coding Standards with Exclusions

Some coding standards include a set of sniffs from an external standard but then exclude some specific sniffs. A sample CodingStandard.php class with exclusions from the PHP_CodeSniffer documentation contains this:

public function getIncludedSniffs()
{
  return array(
          'PEAR',
         );

}//end getIncludedSniffs()

public function getExcludedSniffs()
{
  return array(
          'PEAR/Sniffs/ControlStructures/ControlSignatureSniff.php',
         );

}//end getExcludedSniffs()

The example above includes the whole PEAR coding standard except for the ControlSignature sniff.

These rules would be replicated in a ruleset.xml file like this:

<?xml version="1.0"?>
<ruleset name="My Standard">
 <description>My custom coding standard</description>
 <rule ref="PEAR">
  <exclude name="PEAR.ControlStructures.ControlSignature"/>
 </rule>
</ruleset>

Notice how the exclusions are grouped with the standard they are being excluded from and how they again use the internal sniff codes instead of full paths to sniff files.

A Practical Example

PHP_CodeSniffer comes with a coding standard called PHPCS, which is the entire PEAR standard as well as some Squiz sniffs thrown in. In version 1.2.2, the PHPCSCodingStandard.php file contains these two functions:

public function getIncludedSniffs()
{
  return array(
          'PEAR',
          'Squiz',
         );

}//end getIncludedSniffs()

public function getExcludedSniffs()
{
  return array(
          'Squiz/Sniffs/Classes/ClassFileNameSniff.php',
          'Squiz/Sniffs/Classes/ValidClassNameSniff.php',
          'Squiz/Sniffs/Commenting/ClassCommentSniff.php',
          'Squiz/Sniffs/Commenting/FileCommentSniff.php',
          'Squiz/Sniffs/Commenting/FunctionCommentSniff.php',
          'Squiz/Sniffs/Commenting/VariableCommentSniff.php',
          'Squiz/Sniffs/ControlStructures/SwitchDeclarationSniff.php',
          'Squiz/Sniffs/Files/FileExtensionSniff.php',
          'Squiz/Sniffs/NamingConventions/ConstantCaseSniff.php',
          'Squiz/Sniffs/WhiteSpace/ScopeIndentSniff.php',
         );

}//end getExcludedSniffs() 

To support version 1.3.0, the ruleset.xml file was created with this content:

<?xml version="1.0"?>
<ruleset name="PHP_CodeSniffer">
 <description>The coding standard for PHP_CodeSniffer.</description>

 <!-- Include the whole PEAR standard -->
 <rule ref="PEAR"/>

 <!-- Include most of the Squiz standard -->
 <rule ref="Squiz">
  <exclude name="Squiz.Classes.ClassFileName"/>
  <exclude name="Squiz.Classes.ValidClassName"/>
  <exclude name="Squiz.Commenting.ClassComment"/>
  <exclude name="Squiz.Commenting.FileComment"/>
  <exclude name="Squiz.Commenting.FunctionComment"/>
  <exclude name="Squiz.Commenting.VariableComment"/>
  <exclude name="Squiz.ControlStructures.SwitchDeclaration"/>
  <exclude name="Squiz.Files.FileExtension"/>
  <exclude name="Squiz.NamingConventions.ConstantCase"/>
  <exclude name="Squiz.WhiteSpace.ScopeIndent"/>
 </rule>
</ruleset>

Questions?

This guide has hopefully provided you without enough information and examples to help you convert your custom coding standards to support PHP_CodeSniffer 1.3.0. If you have any questions, please ask them in the comments section below or contact Greg Sherwood directly via the PEAR website.

How much does your coding standard check?

Or maybe the title should be: How Annoying is PHP_CodeSniffer for you? or so the devs around here say. But should they be believed? Are they actually serious or just having a dig?

I've just finished adding error codes to all error and warning messages in PHP_CodeSniffer. This has now allowed me, for the first time, to really take a good look at just how many things each of the included standards are checking.

Obviously, the standards check for a wide range of different violations. Some are formatting issues. Some are performance issues. Most are a matter of preference, defined for the sake of having a standard that everyone in a diverse team can follow. The only differentiation that can be easily made is if something is serious enough to be considered an error, so that's what I'm working with.

The table below lists the complete standards that are included in PHP_CodeSniffer. The Zend and Generic standards are not listed because they are really more of a collection of tools rather than a complete and defined standard. Each standard in the table lists the number of discrete checks being made during a run and the percentage of those checks that produce errors instead of just warnings.

Interestingly, the error percentages for all the standards are about the same. So these coding standards have a few warnings, but the vast majority of their checks are considered important enough to throw errors. There is little room for variation. I personally like this in a standard. Standards that give you a few guidelines or provide you with ambiguous messages and not useful for a developer. If you can't check for it and provide an alternative syntax, save it for the formal code review process.

So how annoying is PHP_CodeSniffer for the developers working on MySource Mini? We are checking 484 different things each time they write a line of code in a PHP, CSS or JS file. So it must be really annoying!

But it's not that bad. You get used to it. You learn the standard and you naturally write code the way everyone has agreed. You make mistakes and they get picked up, but they are easy to find and easy to correct.

When used in this way, PHP_CodeSniffer is the educational tool it was designed to be. It was never intended for developers to be able to write code in whatever style they want and then run a tool to tell them how to make it conform. What a waste of developer time that would be.

As a developer, your job is to solve problems by writing code. The way you write it should be flexible enough that it can change between companies and projects. Hopefully PHP_CodeSniffer can help you learn a new style more easily than just reading a guide and let you know when you are drifting back to an old style.

PHP_CodeSniffer 1.3.0a1 released

PHP_CodeSniffer version 1.3.0 alpha 1 has just been uploaded to PEAR and is now available to install. There have been some major architectural changes in this version, including a complete rework of the way custom standards are written.  Some the highlights in this release are:

• All CodingStandard.php files have been replaced by ruleset.xml files
• A new Git Blame report contributed by Ben Selby
• Support for PHP_Timer, if you have it installed
• Improved support for namespaces
• Improved JavaScript tokenizer support

New features have been (mostly) documented and will be  available on the PHP_CodeSniffer documentation page once the documentation regenerates over the weekend. Documentation for custom standards still needs to be re-written, but you can read more about how to write custom standards with 1.3.0a1 in a previous blog post.

You can view the full changelog on the PHP_CodeSniffer download page.

PHP_CodeSniffer ruleset.xml support available in SVN

The current SVN checkout of PHP_CodeSniffer contains some really big changes to the way custom standards are written and used. The changes make it much easier to create and distribute your own coding standards, giving you the flexibility to pick and choose from the available sniffs and override some of the internal rules the sniffs use, like line lengths and messages.

Creating a custom coding standard

Before ruleset.xml support was added to PHP_CodeSniffer, you needed to write a PHP class for all custom standards. This class had to reside at the top level of your standard's directory structure and extend PHP_CodeSniffer_Standards_CodingStandard. This class was used to both indicate that you have a custom standard and provide a list of sniffs or standards you want to include or exclude.

This file is no longer used. Instead, you must provide a ruleset.xml file (called ruleset.xml) if you wish to distribute a custom standard with your own sniffs. If you do not have any sniffs to distribute and you simply want to use some of the sniffs that are distributed with PHP_CodeSniffer, you only need a single XML file, named whatever you want.

The format is really easy. Here is a very simple ruleset.xml file for a custom standard for PHP_CodeSniffer itself. It uses the whole PEAR standard but also grabs some of the Squiz sniffs. It does this by including the whole Squiz standard and then excluding some specific sniffs from it.

<?xml version="1.0"?>
<ruleset name="PHP_CodeSniffer">
 <description>The coding standard for PHP_CodeSniffer.</description>

 <!-- Include the whole PEAR standard -->
 <rule ref="PEAR"/>

 <!-- Include most of the Squiz standard -->
 <rule ref="Squiz">
  <exclude name="Squiz.Classes.ClassFileName"/>
  <exclude name="Squiz.Classes.ValidClassName"/>
  <exclude name="Squiz.Commenting.ClassComment"/>
  <exclude name="Squiz.Commenting.FileComment"/>
  <exclude name="Squiz.Commenting.FunctionComment"/>
  <exclude name="Squiz.Commenting.VariableComment"/>
  <exclude name="Squiz.ControlStructures.SwitchDeclaration"/>
  <exclude name="Squiz.Files.FileExtension"/>
  <exclude name="Squiz.NamingConventions.ConstantCase"/>
  <exclude name="Squiz.WhiteSpace.ScopeIndent"/>
 </rule>

</ruleset>

If we assume this file is called phpcs.xml, to use this standard with PHP_CodeSniffer you simply run the command:

phpcs --standard=/path/to/phpcs.xml /path/to/code

No need for a directory structure or special naming. And obviously this single file is easy to distribute, maintain and document.

Overriding sniffs options

One of the biggest frustrations when building a custom standard, or even just using an existing one, has been the inability to easily override some of those sniff-specific options. For example, when the Line Length sniff should generate a warning; at 80 chars, 85 chars, 90 chars or another length.

Previously, you had to create your own sniff class that extended the main Line Length sniff and overrode the protected member var. Now, you can do it directly from your ruleset.xml file without needing to create any PHP classes.

Suppose you love the PEAR standard, but you hate the fact that it generates a warning when your line is 85 characters long because you would rather have it happen at 90 characters. Now you can create your own ruleset.xml file, mypear.xml:

<?xml version="1.0"?>
<ruleset name="My PEAR">
 <description>The PEAR standard, but warnings at 90 chars.</description>

 <!-- Include the whole PEAR standard -->
 <rule ref="PEAR"/>
 
 <!-- Lines can be no longer than 90 chars -->
 <rule ref="Generic.Files.LineLength">
  <properties>
   <property name="lineLimit" value="90"/>
  </properties>
 </rule>

</ruleset>

Now run PHP_CodeSniffer like this:

phpcs --standard=/path/to/mypear.xml /path/to/code

Changing sniff messages

The new ruleset.xml file also allows you to customise the messages that sniffs produce. For those messages with variables inside them, you use a sprintf format. Just add this to your ruleset.xml file to change the TODO sniff's warning message:

<rule ref="Generic.Commenting.Todo.CommentFound">
 <message>Please review this comment: %s</message>
</rule>

Or even use this feature to provide translations:

<rule ref="Generic.Commenting.Todo.CommentFound">
 <message>Lütfen bu yorumu gözden geçirin: %s</message>
</rule> 

Changing sniff severity levels

Another new feature available in SVN is the ability for PHP_CodeSniffer to filter out errors and warnings based on a severity level. By default, all errors and warnings have a severity of 5 and PHP_CodeSniffer will show them all. This feature needs its own blog post, but it revolves around the ruleset.xml file as well so I wanted to include it briefly here.

Here is an example of making the TODO sniff less severe. You may want to do this so it does not appear when running PHP_CodeSniffer normally, but you can do a full run to get all warnings during a manual code review:

<rule ref="Generic.Commenting.Todo.CommentFound">
 <severity>3</severity>
</rule> 

A complete example

The following sample file does pretty much everything you can do with this new ruleset.xml file format:

<?xml version="1.0"?>
<ruleset name="Sample">
 <description>A sample coding standard</description>

 <!-- Include all sniffs in the PEAR standard -->
 <rule ref="PEAR"/>

 <!-- Include all sniffs in an external standard directory -->
 <rule ref="/home/gsherwood/standards/mystandard"/>

 <!-- Include everything in another ruleset.xml file -->
 <rule ref="/home/gsherwood/standards/custom.xml"/>

 <!-- Include all sniffs in the MySource standard except one -->
 <rule ref="MySource">
  <exclude name="MySource.Channels.DisallowSelfActions"/>
 </rule>

 <!-- Include some specific sniffs -->
 <rule ref="Generic.CodeAnalysis.UnusedFunctionParameter"/>
 <rule ref="Generic.Commenting.Todo"/>
 <rule ref="Generic.ControlStructures.InlineControlStructure"/>

 <!-- Drop the severity of the todo sniff and change the message -->
 <rule ref="Generic.Commenting.Todo.CommentFound">
  <message>Please review this TODO comment: %s</message>
  <severity>3</severity>
 </rule>

 <!-- Change the settings of the Line Length sniff -->
 <rule ref="Generic.Files.LineLength">
  <properties>
   <property name="lineLimit" value="90"/>
   <property name="absoluteLineLimit" value="100"/>
  </properties>
 </rule>

  <!-- Change both Line Length messages -->
 <rule ref="Generic.Files.LineLength.MaxExceeded">
  <message>Line contains %s chars, longer than the max of %s</message>
 </rule>
 <rule ref="Generic.Files.LineLength.TooLong">
  <message>Line longer than %s chars; has %s chars</message>
 </rule>

 <!-- Disable internal message for missing code and short open tags -->
 <rule ref="Internal.NoCodeFound">
  <severity>0</severity>
 </rule>
</ruleset> 

An alpha release of PHP_CodeSniffer 1.3.0 will happen this week or next. So you can grab the code from SVN directly or wait for this alpha release. Developers of existing custom standards should use this long alpha/RC release process to convert their PHP classes to the new ruleset.xml format.

PHP_CodeSniffer 1.2.2 released

PHP_CodeSniffer version 1.2.2 has just been uploaded to PEAR and is now available to install. Most of the changes are behind-the-scenes, but some of the highlights are:

• An interactive reporting mode to check large code bases and make changes as you go
• Closure support added into the core so sniffs can now check rules for PHP closures
• A completely rewritten reporting system to make everything much easier to extend
• Sniff violation codes that will be used to allow overriding of error messages in the future

All new features have been fully documented and are available on the PHP_CodeSniffer documentation page.

You can view the full changelog on the PHP_CodeSniffer download page.

PHP_CodeSniffer interactive mode

PHP_CodeSniffer is traditionally run over a set of files and a report printed after the run. A developer then uses the report to fix the errors and rechecks the files manually. This can be quite time consuming for large code bases because the error list may be long or may change as other errors are fixed. To make this process easier, a new interactive mode has just been committed to the PHP_CodeSniffer SVN repository.

When PHP_CodeSniffer is asked to run interactively, it will stop checking files as soon as it finds one with errors. It will then print the error report for this file and wait for user input. The idea here is that you go away, fix the errors in the file (focusing on one file at a time) and then ask PHP_CodeSniffer to recheck the file. If the errors are now gone, PHP_CodeSniffer will continue checking the code base from where it left off. If more errors are found, the new error report is shown for the file. You also have to option of skipping the file if you would prefer to fix the errors later.

The following example shows some sample output from interactive mode. This mode is enabled using the -a command line argument.

$ phpcs -a temp.php

FILE: /Users/gsherwood/PHP_CodeSniffer/trunk/temp.php
--------------------------------------------------------------------------
FOUND 2 ERROR(S) AND 1 WARNING(S) AFFECTING 1 LINE(S)
--------------------------------------------------------------------------
 2 | WARNING | Inline control structures are discouraged
 2 | ERROR   | Missing file doc comment
 2 | ERROR   | TRUE, FALSE and NULL must be lowercase; expected "true" but
   |         | found "TRUE"
--------------------------------------------------------------------------

<ENTER> to recheck, [s] to skip or [q] to quit :

Interactive mode also works with all other PHP_CodeSniffer command line options. So you can set the report format and standard to use, if you want to hide warnings, if you'd like to display verbose output, which files to ignore, etc.

So grab a copy of PHP_CodeSniffer from the SVN repository and give it a go. Just add -a to your normal PHP_CodeSniffer command. If you prefer to wait until the release, this feature will be in version 1.2.3 and released as stable in a few weeks time.

Big plans for PHP_CodeSniffer

We've just put together our development plan for PHP_CodeSniffer 1.3.0 and it contains some great features that are going to make it dead-simple to customise the built-in standards without having to write any PHP code.

The biggest change is the concept of violation codes for sniffs. Currently, each sniff can throw different errors and warnings using different error messages, but there is no way to target each of them. Sniffs can now specify violation codes so each of those errors and warnings can be uniquely identified within PHP_CodeSniffer. We'll be adding violation codes for all sniffs that ship with PHP_CodeSniffer. For developers who have written their own sniffs, you can start testing violation codes now as this feature has just been committed to the PHP_CodeSniffer SVN repository.

To add a violation code, you simply specify a third argument to the addError() and addWarning() methods:

$error = 'Line exceeds maximum length of 85 characters';

$phpcsFile->addError($error, $stackPtr, 'LineTooLong'); 

The goal of the violation code development is to make it easy for developers to customise the messages and severities of errors and warnings. You will be able to do this via a ruleset.xml file (similiar to this one) where you can customise as much or as little of a standard as you want. You'll be able to translate messages into other languages, add more useful information into the messages for your team, turns errors into warnings, turn warnings into errors and even remove errors and warnings from the standard all together. And all this via a simple XML file.

Severities are also something we are working on. Currently, PHP_CodeSniffer only has two severity levels; error and warning. We are going to maintain these two different types of messages but add severity levels to them. So instead of having just 5 errors and 2 warnings, you might have 1 severity 10 error, 4 severity 4 errors and 2 severity 7 warnings. You can use the error and warning categories to decide between issues that must be fixed and issues they should be looked at, but then go a step further and decide on a severity to help you prioritise reviews. All these severities will be set in the ruleset.xml file, so sniff developers don't need to do anything if they are happy with the default values we will provide when adding errors and warnings. All reports will get an option to filter errors and warnings by a severity level that you define.

Once we have all this going, the next logical step we are looking at is to allow this ruleset.xml file to define parameters for sniffs. The line length sniff is a great example of where this would be useful. You may be using the PEAR standard, so you will see warnings for all lines over 85 characters in length. With this new feature, you could add a line into the ruleset.xml file so that when you run the PEAR standard you would only see warnings for lines longer than 95 characters. Previously, you had to write your own standard and custom sniff to override the protected member var of the PEAR sniff. With this feature, it will be as easy as an XML tag.

Lastly, we are restructuring the reporting system to remove all the report code out of CodeSniffer.php and put it into separate classes. This not only cleans the code up a bit and ensures we don't load any code we don't need, but it will also make it possible for you to write custom reports for to help you integrate PHP_CodeSniffer with other applications in your development and integration environments.

So that's an awful lot of development headed for PHP_CodeSniffer. Some of the smaller changes will roll out in the 1.2.x releases for developer testing, but most will not be available until a 1.3.0beta1 release sometime early next year. We'll keep you posted.

PHP_CodeSniffer 1.2.1 released

PHP_CodeSniffer version 1.2.1 has just been uploaded to PEAR and is now available to install. It's been exactly 3 months since the 1.2.0 release and plenty of changes have made it into this version, including a few new features as well.

Some of the highlights are:

• A new report type called svnblame that allows you to see which developers are causing the most errors
• The ability to set the report width for all reports, which is really useful for developers with larger screens
• The addition of @codingStandardsIgnore comments to tell PHP_CodeSniffer to ignore parts of a file or the entire file

There have also been some great changes made to the CSS and JavaScript tokenizers to improve their stability.

All new features have been fully documented and are available on the PHP_CodeSniffer documentation page.

You can view the full changelog on the PHP_CodeSniffer download page.