Joomla CodeSniffer

A Nose For Joomla

This is a custom coding standard for the PHP CodeSniffer that attempts to codify and enforce the Joomla coding standards. This article covers how to set the automatic code style checker. It consists of three steps:

1. Install PHP CodeSniffer (phpcs).
2. Clone the Joomla Code Style (for use with for phpcs).
3. Configure your IDE to work with PHP CodeSniffer and Joomla Code Style.

PHP Code Sniffer in action

Why?

- Coherent and consistent 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, sometimes developers will reformat the code to suit themselves. This causes a wide range of changes in the code repository. If there is a later problem, a significant change could be lost in the chaff produced by a diff.

1. Installation of PHP Code Sniffer (phpcs)

Composer (recommended)

PHP Code Sniffer is available via Composer. It can be installed system-wide with the following command:

composer global require 'squizlabs/php_codesniffer=1.*'

On Linux PHP Code Sniffer (phpcs) will be installed under your user folder:

• Symbolic Link: ~/.composer/vendor/bin/phpcs
• The file: ~/.composer/vendor/squizlabs/php_codesniffer/scripts/phpcs

or (for example OpenSuse)

• Symbolic Link: ~/.config/composer/vendor/bin/phpcs
• The file: ~/.config/composer/vendor/squizlabs/php_codesniffer/scripts/phpcs

On Windows PHP Code Sniffer (phpcs) will be installed under your user folder:

• Symbolic Link: c:\Users\Username\AppData\Roaming\Composer\vendor\bin\phpcs
• The file: c:\Users\Username\AppData\Roaming\Composer\vendor\squizlabs\php_codesniffer\scripts\phpcs

PEAR

First you have to install the PHP CodeSniffer. This set of files is intended to work with phpcs version 1.4, so behavior with any other version is undefined. One way to do this is to start the console (cmd.exe in windows environments) and type:

pear install PHP_CodeSniffer

To specify a specific version of the PHP CodeSniffer, type:

pear install PHP_CodeSniffer-1.5.x (specify a number for x, in June 2016 was 1.5.6)

Important note: currently the latest PHPcs is the 2.x series. But they are under development so Joomla Sniffers are not yet compatible with this 2.x version. PEAR gives you the option to install it by default but since Joomla sniffers will not work, always install PHPCS 1.5. version not 2.0.

PEAR will handle the whole installation by itself.

A note for windows users: If you are using XAMPP, while installing the PHPCS make sure in cmd.exe the path is set to <path-to-xampp>xampp/php. After that use codeː pear install PHP_CodeSniffer-1.5.x to install PHPCS. Sometimes while running the command pear install PHP_CodeSniffer-1.5.x in cmd.exe user may get these 2 error like:
1. C:\xampp\php>pear install PHP_CodeSniffer-1.5.6 No releases available for package "pear.php.net/PHP_CodeSniffer"install failed
Just clear the cache using the command: pear clear-cache
After that you are good to go.
2. ERROR: failed to mkdir C:\php\pear\tests\PHP_CodeSniffer\CodeSniffer\Core\File
This error arises because config values set for different pear related directories are wrong.
Use the following command one by oneː
1. pear config-set doc_dir <PATH-TO-XAMPP>\xampp\php\pear(e.g.pear config-set doc_dir C:\xampp\php\pear)
2. pear config-set cfg_dir <PATH-TO-XAMPP>\xampp\php\pear
3. pear config-set data_dir <PATH-TO-XAMPP>\xampp\php\pear
4. pear config-set test_dir <PATH-TO-XAMPP>\xampp\php\pear
5. pear config-set www_dir <PATH-TO-XAMPP>\xampp\php\pear

Then download and unzip the Joomla! CodeSniffer and copy the contents of it into /path/to/PHP_CodeSniffer/Standards/Joomla.

In Unix systems this path is usually /usr/lib/php/PHP/PHP_CodeSniffer/Standards/Joomla but this varies from system to system. In Xubuntu 12.04, the path is /usr/share/php/PHP/CodeSniffer/Standards/Joomla. Windows based system with XAMPP have the following path: PATH_TO_XAMMP\php\PEAR\PHP\CodeSniffer\Standards (for example: C:\xampp\php\PEAR\PHP\CodeSniffer\Standards)

Use

pear config-get php_dir

to find out where the PEAR directory is on your system. Then add "/PHP/PHP_CodeSniffer/Standards" to it.

2. Clone Joomla Codestyle

In order to have PHP Code Sniffer (phpcs) sniffing your Joomla projects for the right code style, you have to clone the Joomla Codestyle into the /CodeSniffer/Standards/ folder of Code Sniffer. That folder already has other folders for styles like PSR1, PSR2, Squiz & Zend.

The location of this folder depends on both your operating system as well as your LAMP/WAMP/MAMP/XAMP/AMP stack. Some popular locations are:

Mac

/Applications/MAMP/bin/php/php7.0.0/lib/php/PHP/CodeSniffer/Standards/

This is for PHP 7.0.0 but this can be another PHP version folder as well.

Linux

~/.composer/vendor/squizlabs/php_codesniffer/CodeSniffer/Standards/

~/.config/composer/vendor/squizlabs/php_codesniffer/CodeSniffer/Standards

Windows

c:\Users\Username\AppData\Roaming\Composer\vendor\squizlabs\php_codesniffer\CodeSniffer\Standards\

This is using Composer on Windows.

If you can't find it in any of the above folders, note that the folder you are looking for ends with \CodeSniffer\Standards\

On Linux, go to the Standards folder of CodeSniffer and git clone from https://github.com/joomla/coding-standards:

$ cd  ~/.composer/vendor/squizlabs/php_codesniffer/CodeSniffer/Standards/ 

or (for example on OpenSuse)

$ cd  ~/.config/composer/vendor/squizlabs/php_codesniffer/CodeSniffer/Standards/ 

and then

$ git clone https://github.com/joomla/coding-standards.git Joomla

You'll end up with a folder like ~/.composer/vendor/squizlabs/php_codesniffer/CodeSniffer/Standards/Joomla/

Usage

You invoke the custom standard by

phpcs --standard=Joomla file/to/sniff

To test a platform file using the provided platform coding standards, use

phpcs --standard=build/phpcs/Joomla path/to/file/or/folder

Further documentation on the use of phpcs can be found at: [1]

3. IDE Integration

Everybody loves the console. It is, with no doubt, the most effective way to do whatever you need to do. Sometimes even Linux gurus need a little bit of comfort.

Fortunately there is a plug-in available for PhpStorm, Eclipse and Netbeans that integrates the CodeSniffer into your favourite IDE, so any coding standard violations are shown like "normal" errors.

PhpStorm

Code Sniffer is supported out of the box in PhpStorm. Go to Settings and under Editor -> Inspections you will see the list of sniffers you have installed.

Set Path to Code Sniffer

1. Open Settings (CTRL-ALT-S / CMD-,)
2. Go to Languages & Frameworks
3. Click on PHP
4. Click on Code Sniffer
5. The configuration is set to Local by default
6. Click on the 3 dots behind it to open the configuration screen
7. The first option is the PHP Code Sniffer (phpcs) path
8. Click on the 3 dots behind the path to select the location of the phpcs file. See above on where phpcs may be installed on your site
9. Click on Validate to make sure the path is correct and phpcs is working
10. Click OK

Activating the Joomla Code Style

1. Open Settings (CTRL-ALT-S / CMD-,)
2. Go to Editor
3. Click on Inspections
4. In the list, go to PHP
5. Click on PHP Code Sniffer Validation
6. Click on the check box behind it to activate it
7. Click the Reload button (2 arrows) to force a reload of rules from disk
8. Joomla should now be available in the list. See following image:

• 
  PHPStorm CodeSniffer

9. Click OK

PHP PSR-0, PSR-1 and PSR-2

• https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md
• https://github.com/pmjones/fig-standards/blob/psr-1-style-guide/proposed/PSR-1-basic.md
• https://github.com/pmjones/fig-standards/blob/psr-1-style-guide/proposed/PSR-2-advanced.md

Using PHP PSR-1 and PSR-2 Sniff

A CodeSniffer sniff to check against the PSR-x Coding Standard can be used as well. In that case you can select a different standard than Joomla.

Using Joomla Code style

It's nice to be able to check that the standards are respected. It's even nicer if PhpStorm helps you format properly too as you are coding. To use the Joomla code style in PhpStorm

1. Open Settings (CTRL-ALT-S / CMD-,)
2. Go to Editor
3. Click on Code Style
4. Select Joomla from the Scheme select box

PhpStorm / Alternative Method

NOTE: This method is outdated, but it might be useful if you are looking for a different integration. It also demonstrates the use of external tools in PhpStorm - so it shouldn't be deleted.

The Code Sniffer can also be integrated easily as an external tool. PhpStorm will display the output in the console, including click-able links containing line and column numbers to the files that contain errors.

• Click on "Settings" and search for "External tools"
• Click "Add..."
• Choose a "Name", "Group" and "Description".
• Click "Output Filters"
  • Click "Add...", Choose a name and enter under "Regular expression to match output" the value: $FILE_PATH$:$LINE$:$COLUMN$
• "Program": Search for the phpcs executable on your system. You have to set the path to the phpcs.bat from the installed PHP_CodeSniffer PEAR package
  • For Unix based systems, the path is something like /usr/bin/phpcs
  • In XAMPP (windows), you can find the file in the PHP root folder (e.g. C:\xampp\php\phpcs.bat)
• "Parameters":
  • --standard=<path/to/joomla-platform>/build/phpcs/Joomla The path to the Joomla! coding standards.
  • --report=emacs The will generate a simple list containing links to the error files
  • Optionally you may want to specify -p for "progress" or -n for "errors only".
  • The last parameter has to be $FilePath$ specifying the file or folder you want to sniff.

A typical "Parameters" line on a Linux system might look like this:

-np --standard=/home/elkuku/libs/joomla/build/phpcs/Joomla --report=emacs $FilePath$

You may now right click any file or folder and choose the sniffer from the context menu or add a new tool bar button with a nice Joomla! logo .

Netbeans

Netbeans has the sniffer functionality integrated into the core system.

1. Start your Netbeans IDE
2. Open Tools => Options => PHP => Code Analysis => Code Sniffer
3. You have to set the path to phpcs.bat from the installed PHP_CodeSniffer PEAR package
   • For Unix based systems the path is something like /usr/bin/phpcs
   • In XAMPP (windows) you can find the file in the PHP root folder (e.g. C:\xampp\php\phpcs.bat)
4. As "Default Standard," choose "Joomla" to use the Joomla! standard
5. Now you can click OK to start sniffing
6. Open from the top menu Source => Inspect...
7. Enjoy

Eclipse

1) Eclipse PTI

Installation is a breeze and follows the usual pattern:

1. Help => Install New Software...
2. Work with: Fill in one of the update site URLs found here: http://www.phpsrc.org/eclipse/pti/
3. Select the desired tools
4. Restart Eclipse.

2) Eclipse PTI settings

You are now able to sniff for code violations against common standards like PEAR or Zend etc.

To sniff against your own standards, specify their location and activate them (see screen shot 2)

1. Window => Preferences
2. PHP Tools => PHP CodeSniffer

Happy sniffing.

PHP Tools Compatibility Issue

PHP Tools does not directly support PHP_CodeSniffer-1.5.x. It reports this error:

PHP Fatal error: Uncaught exception 'PHP_CodeSniffer_Exception' with message 'Class PHP_CodeSniffer_CommentParser_ClassCommentParser not found' in /usr/share/php5/PEAR/PHP/CodeSniffer/Standards/Joomla/Sniffs/Commenting/FileCommentSniff.php:18

It comes with a pre-packaged CodeSniffer version located in eclipse/plugins/org.phpsrc.eclipse.pti.library.pear_.../php/library/PEAR/PHP. To fix the issue, just remove the pre-packaged CodeSniffer version and link the local version. For example, /usr/share/php/PHP.

ln -s /usr/share/php/PHP /home/.../eclipse/plugins/org.phpsrc.eclipse.pti.library.pear_.../php/library/PEAR/PHP

In any case, you can also debug a PHP Tools issue, enabling the debug mode to show the internal commands in Eclipse console:

1. Window => Preferences
2. PHP Tools => PHP CodeSniffer
3. Debug: print PHP output to console

Command example:

/usr/bin/php -c /tmp/zend_debug/session8314597725413224814.tmp -d asp_tags=off -d short_open_tag=on /home/.../eclipse/plugins/org.phpsrc.eclipse.pti.tools.codesniffer_1.3.0.R20111119000000/php/tools/phpcs.php --report=xml --standard=/home/.../Joomla /home/..../myphpfile.php

Geany

• Open a PHP file (otherwise the build menu is not accessible) Screenshot
• Select menu Build->Set build commands
• Select the second field, name it as you wish and enter code phpcs --standard=Joomla "%f" | sed -e 's/^/%f |/' | egrep 'WARNING|ERROR'
• Enter Error regular expression (.+) [|]\s+([0-9]+) and press ok Screenshot
• Now press F9 to see the errors found Screenshot

References

• http://www.phpsrc.org/ PTI - PHP tools integration for Eclipse
• http://sourceforge.net/projects/phpmdnb/ Netbeans plugin
• http://hakre.wordpress.com/2010/03/06/php-code-sniffer-eclipse-and-wordpress/ - Excellent article. Just change "Wordpress" for "Joomla!" ;)