¶ ↑
A Nose For JoomlaThis is a custom coding standard for the PHP CodeSniffer that attempts to codify and enforce the Joomla coding standards.
¶ ↑
Why?The reasons seem obvious, but one look at reality shows they aren’t, so I’ll enumerate some of them here:
-
Coherent and consisting coding practice makes the files look more professional. Conflicting styles in the same project (or worse, the same file) not only look sloppy, they encourage further sloppiness.
-
When all code complies with the same standard, bad code is easier for everyone to spot.
-
It makes it easier for someone new to a particular file in the project to find and fix errors, or extend functionality.
-
If there is no consistent standard maintained, the sometimes developers will reformat the code to suit themselves. This causes a wide range of changes in the code repository, and if there is a later problem, a significant change could be lost in the chaff produced by a diff.
¶ ↑
Why This Particular Coding Standard?The short answer is “Don’t ask me. I didn’t make that decision.”
I don’t hold a brief for any particular coding standard over any other one. I’ve coded in many, and I expect I’ll be asked to code in many more before I’m done.
The main point is What standard you use isn’t as important as all developers on a project using the same one.
The Joomla development team agreed on this standard (docs.joomla.org/Coding_style_and_standards) and that document is the source of the rules found here. Consider that page definitive in any point where it differs from this output.
¶ ↑
InstallationFirst you’ll need to install phpcs (pear.php.net/package/PHP_CodeSniffer/download/). This set of files is intended to work with phpcs version 1.3, so behavior with any other version is undefined.
Then download and unzip this repository, and copy the contents of it into /path/to/PHP_CodeSniffer/Standards/Joomla. (The path on my system is /usr/lib/php/PHP/PHP_CodeSniffer but it varies from system to system. Use
pear config-get php_dir
to find out where the PEAR directory is on your system, then add “/PHP/PHP_CodeSniffer” to it.)
Then you invoke the custom standard by
phpcs --standard=Joomla --tab-width=4 file/to/sniff
Further documentation on the use of phpcs can be found at: pear.php.net/package/PHP_CodeSniffer/docs
¶ ↑
Unit Testing NoteThe PHPCodeSniffer unit testing structure is unable to handle changes from the default configuration, so most unit tests written that depend upon that (such as the SwitchDeclarationSniff) will fail. This is caused by the fact the Joomla standard currently permits, even prefers, tabs for indents, rather than spaces, and phpcs doesn’t seem to be able to handle that without configuration options, and the unit testing framework as it exists prohibits that.
Therefore those functions have not been unit tested, and instead been tested the old-fashioned way, by supplying test files to the sniffer and examining results. If you find a bug there, post it to the tracker.
¶ ↑
Revision History* 0.2 – Basic functionality complete * 0.3 – Sniffs different if structure and @param element layout * 0.9 – Adheres to revised Joomla Coding Standard * 1.0 – Released with Unit tests (such as they are)