PHP CodeSniffer tips

I really love tools which help my code be more correct and more readable. I have referred to tools like JSLint (JS) and FindBugs (Java) in previous posts and now I am going to write some tips about using PHP CodeSniffer (PHP) (a.k.a. phpcs). It is probably the most aggressive of the three and can be especially tricky on the requirements it puts on your file headers.

Here is a sample file header:

<?php
/**
* Presto - a lightweight REST framework for PHP
*
* Presto is a simple to use and very lightweight REST framework for PHP,
* it will help you to handle rest routing and input/output of data without
* getting in your way
*
* PHP Version 5
*
* LICENSE:
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
* http://www.apache.org/licenses/LICENSE-2.0
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*
* @category  File
* @package   Presto
* @author    Aaron Zeckoski <azeckoski@vt.edu>
* @copyright 2009 Aaron Zeckoski
* @license   http://www.apache.org/licenses/LICENSE-2.0 Apache License, Version 2.0
* @version   SVN: $Id:$
* @link      https://link/to/your/project/site
* @since     inception
*/

A few comments about the header:

• The copyright cannot have a comma after the year but the year can be a range. "2002-2009 AZ" is ok, "2009, AZ" is not
• The license should appear inside the header like shown, not above it (this would cause an ERROR in phpcs)
• The alignment of the data after the tags (e.g. @license, @version) is not optional, misaligned data causes an ERROR

Sample class:

/**
* My class which does some stuff
*
* @category Class
* @package  Presto
* @author   Aaron Zeckoski <azeckoski@vt.edu>
* @license  http://www.apache.org/licenses/LICENSE-2.0 Apache License, Version 2.0
* @link     https://link/to/the/project/again
*/
class RestController
{
 const DEFAULT_RESOURCES_DIR = 'resources';

 /**
  * This is a method in my class
  *
  * @param object $_resourcesPath [optional] the resource path
  *
  * @return void
  */
 protected function loadResources($_resourcesPath = self::DEFAULT_RESOURCES_DIR)
 {

There are also a few of the rules about classes that caught me out as well:

• Class methods must use camelCase. myMethodName is good, my_method_name is not
• Classes MUST have a comment on them and it has to include a lot of the fields from the header. The ones I list in the sample above are the minimum (seriously).
• The space between @params and @return is not optional
  
• Just a note on constants in PHP, you use const inside classes and define outside

Take a look at the sample file and class headers here for more details: http://pear.php.net/manual/en/standards.sample.php