This started out sometime early this year as an exercise to create a set of Code Sniffs which could be applied to our CakePHP projects…
Ummm… I guess, at this point I should rewind a bit and give a couple of background definitions and some more..
- PHP_Codesniffer A PEAR package tokenises PHP and JavaScript code and detects violations of a defined set of coding standards.
- Code sniffs a set of scripts which define coding standards
- PHP_Codesniffer manual gives adequate instructions on installation and usage
- Tutorial for creating sniffs
Initially I had thought that I will just use one of the pre-packaged sniffs but the first difficulty that I ran into was with $anything->something – in CakePHP if the “something” is an object then it begins with an uppercase alphabet but a variable or method name begins with a lowercase alphabet, thus $anything->Something == Object. Tinkering around the code a bit made it apparent that I had to have my own set of Cake sniffs to manage this but a separate standard just for this seemed an over kill and the simplicity of code made it kind of fun to add more standards which I liked but were in different set of sniffs
So I added the disallow short open tags sniff, then the Uppercase Constants sniff and soon the list was
- public function getIncludedSniffs()
- {
- return array(
- 'Generic/Sniffs/PHP/DisallowShortOpenTagSniff.php',
- 'Generic/Sniffs/NamingConventions/UpperCaseConstantNameSniff.php',
- 'Generic/Sniffs/WhiteSpace/',
- 'Generic/Sniffs/Formatting/MultipleStatementAlignmentSniff.php',
- 'PEAR/Sniffs/Classes/ClassDeclarationSniff.php',
- 'PEAR/Sniffs/ControlStructures/ControlSignatureSniff.php',
- 'PEAR/Sniffs/Files/LineEndingsSniff.php',
- 'PEAR/Sniffs/Functions/FunctionCallArgumentSpacingSniff.php',
- 'PEAR/Sniffs/Functions/FunctionCallSignatureSniff.php',
- 'PEAR/Sniffs/Functions/ValidDefaultValueSniff.php',
- 'PEAR/Sniffs/Commenting/',
- 'PEAR/Sniffs/NamingConventions/ValidClassNameSniff.php',
- 'Squiz/Sniffs/Functions/GlobalFunctionSniff.php',
- 'Squiz/Sniffs/ControlStructures/InlineIfDeclarationSniff.php',
- 'Squiz/Sniffs/Arrays/ArrayDeclarationSniff.php',
- 'Squiz/Sniffs/WhiteSpace/FunctionSpacingSniff.php',
- 'Squiz/Sniffs/Commenting/ClosingDeclarationCommentSniff.php',
- 'Squiz/Sniffs/Commenting/VariableCommentSniff.php',
- 'Zend/Sniffs/Files/ClosingTagSniff.php'
- );
- }//end getIncludedSniffs()
The only sniff I was missing was something which counts the number of lines in a function and restricts them to 45. Why 45? because those many lines fit in one screen full of Eclipse editor in the layout we commonly use… The end result was FunctionLineCountSniff.php
And the tyrant that I am I put in a SVN pre-commit hook (also supplied in the package) into our local SVN setup – so now if any of the developer misses/truants out on any of the standards they get an angry red output in their Eclipse console, something like
svn: 'pre-commit' hook failed with error output: FILE: trunk/app/controllers/clients_controller.php -------------------------------------------------------------------------------- FOUND 1 ERROR(S) AND 0 WARNING(S) AFFECTING 1 LINE(S) -------------------------------------------------------------------------------- 71 | ERROR | Missing function doc comment --------------------------------------------------------------------------------
There were a few cribs initially but soon everyone got used to it and we now have code which looks uniformly pretty – Code pretty? Oh! well I will leave that for some other time…. right now I am working on a version of Bake which bakes using most of these standards – will save a lot of work.
Meanwhile if anyone wants to use these code sniffs feel free to download them here
It would be cool if the cake team would also use those code sniffs
I will be happy enough if bake output was phpDoc commented and bake allowed multiple rules of validations but I guess incorporating patches into bake is a low priority right now…
We are considering to implement this for the Cake Testsuite maybe.
@Tim – that indeed would be a welcome addition!
Hey, couple things:
(1) I started on a set of sniffs a few weeks ago but never finished, so I might just steal yours.
(2) There was a ticket on adding docblock-generation to Bake, but someone must have shot it down, because I don’t see it in there. Anyway, if you have a patch against the current codebase, attach it to a ticket and assign it to me, I’ll get it in there.
Validation though… not so much.
I’d rather keep Bake as light and focused as possible, and that’s something that’s simple enough to do without stepping through command prompts.
Hi Nate, Life would be easier for me if Cake itself had a set of code sniffs – so I should say thanks
Also I will be happy to make any modifications to the sniffs if needed.
I had seen the last docblock patch and had not liked it too much – will definitely post a ticket once I have something ready.
@nate – The ticket in which patch included to bake with phpDoc comments is #4276
Hey Tarique, I’ll let you know about the patches as soon as I can. I’d like to do another release in the next week or two, so if you can work up a patch for Bake by then, that’d be great. If not, no worries. Thanks.
Interesting. I am going to have to look into Cake. It sounds fun.