PHP_CodeSnifer coding standard tutorial updated

In my last post, I mentioned that the current PHP_CodeSniffer manual doesn't have any information about using an external standard. The manual, and coding standard tutorial, assume that the standard you are writing and testing with is located within the main PHP_CodeSniffer directory structure. This is not normally the case, so I have updated the manual to be a little more realistic.

The coding standard tutorial now takes you through the process of creating an externally managed coding standard rather than instructing you to create your standard within PHP_CodeSniffer's Standards directory. This not only documents the usage of external standards, but also makes it much easier for would-be standard developers to get started.

The updated tutorial wont be available on the PEAR site until Sunday/Monday, but you can view it on Brett Bieber's build right now. From next week, you can view it at the normal place.

As a side note, creating and compiling the manual (peardoc) on Linux is a lot easier than on OS X. I am now using a Fedora 8 VM for all my PHP_CodeSniffer development and documentation work and I highly recommend this setup.

PHP_CodeSniffer update

It's been a while since I've posted about PHP_CodeSniffer, which is probably because nothing of great interest has been happening in the project. I'm pushing forward for a 1.1.0 stable release (the first stable with JavaScript code sniffing support) and have just released version 1.1.0RC3. I'm hoping that this will be the last release candidate before the stable.

So it's been a fairly boring period of time where I haven't wanted to add any new features for fear of destabilising the code, but some changes are on the horizon now, and they should be welcome additions.

The first of these is copy/paste detection, allowing PHP_CodeSniffer to find duplicate code throughout a project and help implement some code reuse. This is a feature PHPUnit currently has, but Sebastian Bergmann has kindly offered to port it to PHP_CodeSniffer as it seems like a better fit for this particular QA feature.

To implement this, I'll be creating a new kind of sniff that will be run after all files have been sniffed. It will be passed PHP_CodeSniffer_File objects for every file tested during the run, allowing the sniff to look into each file and do project-level checking. Errors will still be reported per file, as they are now.

The other feature PHP_CodeSniffer seems destined to get is the separation of the main code sniffing core from the standards. Coding standards can already be run without having to live inside the PHP_CodeSniffer standards directory (more on that later) but unit tests can not be correctly run in this scenario. This feature should make it easier for developers to distribute their own coding standards and introduce dependencies between standards and the core.

I have tried doing this before, but I could never get the PEAR installer to write the unit tests to the directory I wanted so I could run all my tests at once. Helgi Þormar Þorbjörnsson has kindly offered to help me resolve my unit testing problems, so I'll hopefully be able to sort out this issue now.

Finally, Stefan Priebsch got a bit fed up with my crappy documentation for external standards and decided to (thankfully) write an article about how to use an external standard with PHP_CodeSniffer. Well worth a read if you're managing your own coding standard. You might even be learning about this little used feature for the first time.

Sebastian Bergmann giving 3-day QA workshop in Oz

Well that is good news. If you want to find about QAing PHP projects, you wont find anyone better than the creator of PHPUnit, Sebastian Bergmann.

This 3-day workshop will introduce the attendees to writing unit tests for the backend and system tests for the frontend of a web application as well as managing the quality from development to deployment and maintainance using tools such as PHPUnit, Selenium RC, phpUnderControl, PHP_CodeSniffer, and PHP_Depend.

It's nice to see such a rich list of QA apps designed specifically for PHP developers and, of course, PHP_CodeSniffer in the list.

The workshop is in Melbourne and costs $1695 + GST. You can read more about it at Open Query.

PHP_CodeSniffer code taken and rebadged as Zend Framework code

A new feature request for PHP_CodeSniffer alerted me to the effort of a couple of Zend Framework developers to create a PHP_CodeSniffer standard that can be used by all Zend Framework developers. The feature request mentioned that the name they had chosen (Zend) conflicts with the existing standard that is distributed with PHP_CodeSniffer.

I immediately thought this was a bit strange because I've already had someone from Zend contribute some code for the Zend Framework coding standard, and I've written a fair few sniffs for it myself.

I took a look at the code and noticed that almost all of the sniffs that have been committed to the Zend Framework SVN repository are just copies of the sniffs I have written for the existing PHP_CodeSniffer standards. The troubling part is that all the copyright notices and author tags have been switched to indicate that the code was written by and copyright Zend. Worse still, the licence had been changed to the Zend Framework's New BSD licence.

This is a pretty clear violation of the BSD licence under which PHP_CodeSniffer is distributed, so I've left a comment on the Coding Standard RC page in the Zend Framework wiki. I tried locating an email address, submitting an issue and even commenting on an existing issue, but it appears the Zend Framework doesn't have any scope for non-approved developer comments besides the wiki.

I did get a little angry when I saw this, but I also see this as an opportunity to complete the PHP_CodeSniffer Zend standard and get PHP_CodeSniffer our there to a new developer community. The Zend Framework obviously has a couple of developers dedicated to automating their coding standard checks using PHP_CodeSniffer, so I've provided them with an invitation to contact me and work together. I will hopefully be taken up on that offer.

Update: Thought it might be easier to see the problem if you can focus on one file. Take a look at Zend's FunctionDeclarationArgumentSpacingSniff (from the ZF SVN repo) and Squiz's FunctionDeclarationArgumentSpacingSniff (from the PEAR CVS repo). Only very minor changes have been made. Even with these changes, it would be best to extend the Squiz sniff and do some minor refactoring rather than copy/paste, which I'm happy to help with.

Update: Thomas Weidner has contacted me to let me know the files have been removed from the Zend Framework SVN repo.

PHP_CodeSniffer 1.1.0a1 released

I've just uploaded PHP_CodeSniffer version 1.1.0a1, which contains 8 bug fixes and adds a load of new features including support for sniffing JavaScript files, an SVN pre-commit hook, integration with JSL and a new collection of sniffs that implement part of the PMD.

Thanks to everyone who has submitted bug reports and special thanks to Jack Bates for the pre-commit hook, Jan Miczaika for a new sniff and Manuel Pichler for bug fixes and the PMD sniffs.

You can view the full changelog, and download the release, on the package download page.

PHP_CodeSniffer and JavaScript Lint

The new JavaScript tokenizer in PHP_CodeSniffer allows you to write your own custom JS sniffs, but JavaScript Lint already has a set of generic tests that can be applied to your code. Thanks to the JavaScript Lint command line tool, jsl, you can now include JavaScript Lint warnings and errors in your coding standards.

I've just committed the JavaScriptLint sniff into the Squiz standard under a new Debug category. The sniff requires you to have jsl installed on the same machine as PHP_CodeSniffer and you need to tell PHP_CodeSniffer where to find it.

$ phpcs --config-set jsl_path /path/to/jsl
$ phpcs --standard=squiz /path/to/file.js

JavaScript Lint checks for a number of common errors, including missing semi-colons and unused code. Like the Zend CodeAnalyzer sniff, not all errors and warnings need fixing, so all messages reported by jsl are warnings within PHP_CodeSniffer and can be hidden easily.

Obscure software bugs always come in pairs

Well, for me anyway, and in MySource Matrix in particular. I don't know what it is, but obscure bugs get reported to me and shortly after I have a fix, I will be fixing the bug on one or two other systems. Yet this bug may have been in the software for years and may be extremely hard to replicate. This has been happening more and more; I think it has been three or four times in the past 12 months, which is just strange.

The strangest case is a bug in a trigger condition that was caused by the way PHP converts strings to numbers. I was so surprised we had never previously encountered the problem that I wrote a blog post on the issue. The night I wrote that post I also committed a fix to MySource Matrix. The very next day I was asked to diagnose a strange problem on another client's system with triggers. The fix I committed the night before also fixed this client's problem.

The latest case reared its head again just today. About a month ago we diagnosed and fixed a strange problem that was caused by IP addresses changing and logging a user out of MySource Matrix during the multiple requests made on the frontend (HMTL, CSS, JS etc). The session is destroyed if you get logged out, but the code that loaded a serialized class didn't first include the class file. We fixed that bug. The next week I diagnosed the same bug on another client's system. Last week I received a support ticket for the same issue. And just today I diagnosed the same problem on a system undergoing implementation. The strange thing is that we have always had systems where users have their IP changing and yet we've never seen this error.

I don't get this so much with PHP_CodeSniffer, although I do tend to fix bugs in CVS only to have someone report it via the PEAR bug tracker. They are not as common or obscure though. Perhaps the size of the project directly relates to the incidence of these sort of bugs.

I think everyone hears that these sort of things happen, and not just with software bugs, but it is still amazing to see how often it occurs.