Actions

Difference between revisions of "Joomla CodeSniffer"

From Joomla! Documentation

(Installing Joomla Sniff)
(34 intermediate revisions by 9 users not shown)
Line 1: Line 1:
(This page needs expanded installation instructions, especially for Windows-based systems.)
+
{{page|needs technical review|This page needs expanded installation instructions, especially for Windows-based systems}}
  
 
== A Nose For Joomla ==
 
== A Nose For Joomla ==
Line 17: Line 17:
 
==Installation==
 
==Installation==
  
First you'll need to install phpcs (http://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.
+
First of all you have to install the [http://pear.php.net/package/PHP_CodeSniffer/ PHP CodeSniffer]. This set of files is intended to work with phpcs version 1.3, 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:
  
Then download and unzip the [http://joomlacode.org/gf/project/jcodesniffer/ Joomla CodeSniffer], and copy the contents of it into /path/to/PHP_CodeSniffer/Standards/Joomla. (The path on some systems is /usr/lib/php/PHP/PHP_CodeSniffer but this varies from system to system. Use  
+
<code>pear install PHP_CodeSniffer-1.3.2</code>
 +
 
 +
Pear will handle the whole installation by itself.
 +
 
 +
Then download and unzip the [https://github.com/joomla/joomla-platform/tree/master/build/phpcs 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  
  
 
<code>pear config-get php_dir</code>
 
<code>pear config-get php_dir</code>
  
to find out where the PEAR directory is on your system, then add "/PHP/PHP_CodeSniffer" to it.)
+
to find out where the PEAR directory is on your system, then add "/PHP/PHP_CodeSniffer/Standards" to it.
  
 
== Usage ==
 
== Usage ==
Line 29: Line 38:
 
You invoke the custom standard by
 
You invoke the custom standard by
  
<code>phpcs --standard=Joomla --tab-width=4 file/to/sniff</code>
+
<code>phpcs --standard=Joomla file/to/sniff</code>
 
+
'''NOTE''': When you are developing for the Joomla platform project, the updated coding style guidelines can be found in the build folder of the github project [https://github.com/joomla/joomla-platform/tree/master/build/phpcs here]. The standard from Joomlacode is not up-to-date. In that case, you also have to ommit the --tab-width=4 parameter.
+
  
 
To test a platform file using the provided platform coding standards use
 
To test a platform file using the provided platform coding standards use
Line 41: Line 48:
 
==IDE integration==
 
==IDE integration==
  
[[Image:eclipse_pti.png|left|thumb|200px|1) Eclipse PTI]]
 
 
While everybody loves the console as 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.
 
While everybody loves the console as 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 plugin available for eclipse (tested) and netbeans (not tested) that integrates the CodeSniffer in our favorite IDE, so any coding standard violations are shown like "normal" errors (see screen shot 1).
+
Fortunately there is a plugin available for eclipse and netbeans that integrates the CodeSniffer in our favorite IDE, so any coding standard violations are shown like "normal" errors.
 +
 
 +
=== Netbeans ===
 +
 
 +
For netbeans you have to install the sniffer plugin first. You can download the plugin [http://sourceforge.net/projects/phpmdnb/files/nbm/ here].
 +
 
 +
# Start your netbeans IDE
 +
# Open Tools => Plugins => Downloaded and press ''Add Plugin''
 +
# Choose the loaded nbm file and confirm the installation
 +
# Now there is a new tab in Tools => Options => PHP called "PHPCodeSniffer"
 +
# 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)
 +
# As "standard" type "Joomla" to use the Joomla! standard
 +
# now you can click ''test Settings'' to check the settings and finish the installation by pressing ''Ok''
 +
# Open he task window (Window => Tasks) to sniff your code.
 +
# Most time it is a good idea to filter the task (show only in edited file or create an own filter which displays only sniff errors)
 +
 
 +
=== Eclipse ===
 +
[[Image:eclipse_pti.png|left|thumb|200px|1) Eclipse PTI]]
 +
 
  
 
<div style="clear: both"></div>
 
<div style="clear: both"></div>
 
Installation is a breeze and follows the usual pattern:
 
Installation is a breeze and follows the usual pattern:
 
# <tt>Help => Install new Software...</tt>
 
# <tt>Help => Install new Software...</tt>
# <tt>Work with:</tt> Fill in one of the update site URLs found here: http://www.phpsrc.org/
+
# <tt>Work with:</tt> Fill in one of the update site URLs found here: http://www.phpsrc.org/eclipse/pti/
 
# Select the desired tools
 
# Select the desired tools
 
# Restart Eclipse.
 
# Restart Eclipse.
Line 55: Line 81:
 
[[Image:eclipse_pti_settings.png|right|thumb|150px|2) Eclipse PTI settings]]
 
[[Image:eclipse_pti_settings.png|right|thumb|150px|2) Eclipse PTI settings]]
 
You are now able to sniff for code violations against common standards like PEAR or Zend etc.
 
You are now able to sniff for code violations against common standards like PEAR or Zend etc.
 
<del>Notice that the PTI project currently is not working right on the Eclipse Indigo releases. If you want to use the Eclipse integration for the PHP_CodeSniffer, use an Eclipse Helios release and install it in there.</del> '''update''' The PTI project has updated it's sources and runs fine in Eclipse Indigo.
 
  
 
To sniff against your own standards, all you have to do is specify their location and activate them (see screen shot 2)
 
To sniff against your own standards, all you have to do is specify their location and activate them (see screen shot 2)
Line 65: Line 89:
 
Happy sniffing
 
Happy sniffing
  
 +
=== PHPStorm ===
 +
 +
==== PHPStorm ====
 +
[[Image:PhpStorm4CodeSniffer.png|left|thumb|200px|1) PHPStorm  4.x CodeSniffer]]
 +
<div style="clear: both"></div>
 +
 +
CodeSniffer is supported out of the box in PHPStorm, just go to settings, and under "Inspections" you will see the list of Sniff you have installed.
 +
 +
See: the [http://www.jetbrains.com/phpstorm/webhelp/using-php-code-sniffer-tool.html JetBrains documentation page for setting the Code Sniffer]  and also  [http://blog.jetbrains.com/webide/2012/03/checking-your-code-with-php-code-sniffer-in-phpstorm-4-0/ phpStorm Blog])
 +
 +
===== Installing Joomla Sniff =====
 +
 +
# get the sniffers from the [https://github.com/joomla/coding-standards coding standards repo]
 +
# unpack Joomla CodeSniffer rules under:
 +
## If you are using XAMPP ''\xampp\php\PEAR\PHP\CodeSniffer\Standards\Joomla''
 +
## If not maybe you should check here: ''/usr/share/php/PHP/CodeSniffer/Standards''
 +
# Go to Settings (CTRL-ALT-S) and search for "PHP Code Sniffer Validation", click the button Validate to force reload of rules from disk
 +
# Joomla should be now available in the list. See following image:
 +
 +
[[Image:PhpStorm6CodeSniffer.png|left|thumb|200px|1) PHPStorm  6.x CodeSniffer]]
 +
<div style="clear: both"></div>
 +
 +
==== 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
 +
 +
===== Installing PHP PSR-0, PSR-1 and PSR-2 Sniff =====
 +
 +
A CodeSniffer sniff to check against the PSR-x Coding Standard
 +
 +
Download files at
 +
* https://github.com/squizlabs/PHP_CodeSniffer/tree/master/CodeSniffer/Standards
 +
 +
if you are using Xampp,
 +
# unpack PSR-1 CodeSniffer rules under \xampp\php\PEAR\PHP\CodeSniffer\Standards\PSR (SPR or any directory will work)
 +
# Go to Settings (CTRL-ALT-S) and search for "PHP Code Sniffer Validation", click the button Validate to force reload of rules from disk
 +
# PSR is available in the list
 +
 +
==== PHPStorm  3.x / 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.
 +
 +
<del>There is currently no plugin available</del> The CodeSniffer can also be integrated easily as an external tool. PHPStorm will display the output in the console, including clickable 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: <tt>$FILE_PATH$:$LINE$:$COLUMN$</tt>
 +
* "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)
 +
* "Paramaters":
 +
** <tt>--standard=<path/to/joomla-platform>/build/phpcs/Joomla</tt> The path to the Joomla! coding standards.
 +
** <tt>--report=emacs</tt> The will generate a simple list containing links to the error files
 +
** Optional you may want to specify <tt>-p</tt> for "progress" or <tt>-n</tt> for "errors only".
 +
** The last parameter has to be <tt>$FilePath$</tt> specifying the file or folder you want to sniff.
 +
 +
A typical "Parameters" line on a Linux system might look like this:
 +
<pre>-np --standard=/home/elkuku/libs/joomla/build/phpcs/Joomla --report=emacs $FilePath$</pre>
 +
 +
You may now right click any file or folder and choose the sniffer from the context menu or add a new toolbar button with a nice Joomla! logo [[File:icon-16-joomla.png]].
 +
 +
=== References ===
 
* http://www.phpsrc.org/ PTI - PHP tools integration for Eclipse
 
* http://www.phpsrc.org/ PTI - PHP tools integration for Eclipse
* http://github.com/beberlei/netbeans-php-enhancements/ Netbeans enhancements
+
* 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!" ;)
 
* http://hakre.wordpress.com/2010/03/06/php-code-sniffer-eclipse-and-wordpress/ - Excellent article. Just change "Wordpress" for "Joomla!" ;)
  
 
[[Category:Development]][[Category:Bug Squad]]
 
[[Category:Development]][[Category:Bug Squad]]

Revision as of 05:22, 21 March 2013

Copyedit.png
This Article Needs Your Help

This article is tagged because it NEEDS TECHNICAL REVIEW. You can help the Joomla! Documentation Wiki by contributing to it.
More pages that need help similar to this one are here. NOTE-If you feel the need is satistified, please remove this notice.

Reason: This page needs expanded installation instructions, especially for Windows-based systems


Contents

A Nose For Joomla

This is a custom coding standard for the PHP CodeSniffer that attempts to codify and enforce the Joomla coding standards.

Why?

- 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.

Installation

First of all you have to install the PHP CodeSniffer. This set of files is intended to work with phpcs version 1.3, 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-1.3.2

Pear will handle the whole installation by itself.

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.

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]

IDE integration

While everybody loves the console as 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 plugin available for eclipse and netbeans that integrates the CodeSniffer in our favorite IDE, so any coding standard violations are shown like "normal" errors.

Netbeans

For netbeans you have to install the sniffer plugin first. You can download the plugin here.

  1. Start your netbeans IDE
  2. Open Tools => Plugins => Downloaded and press Add Plugin
  3. Choose the loaded nbm file and confirm the installation
  4. Now there is a new tab in Tools => Options => PHP called "PHPCodeSniffer"
  5. 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)
  6. As "standard" type "Joomla" to use the Joomla! standard
  7. now you can click test Settings to check the settings and finish the installation by pressing Ok
  8. Open he task window (Window => Tasks) to sniff your code.
  9. Most time it is a good idea to filter the task (show only in edited file or create an own filter which displays only sniff errors)

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, all you have to do is specify their location and activate them (see screen shot 2)

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

Happy sniffing

PHPStorm

PHPStorm

1) PHPStorm 4.x CodeSniffer

CodeSniffer is supported out of the box in PHPStorm, just go to settings, and under "Inspections" you will see the list of Sniff you have installed.

See: the JetBrains documentation page for setting the Code Sniffer and also phpStorm Blog)

Installing Joomla Sniff
  1. get the sniffers from the coding standards repo
  2. unpack Joomla CodeSniffer rules under:
    1. If you are using XAMPP \xampp\php\PEAR\PHP\CodeSniffer\Standards\Joomla
    2. If not maybe you should check here: /usr/share/php/PHP/CodeSniffer/Standards
  3. Go to Settings (CTRL-ALT-S) and search for "PHP Code Sniffer Validation", click the button Validate to force reload of rules from disk
  4. Joomla should be now available in the list. See following image:
1) PHPStorm 6.x CodeSniffer

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

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

A CodeSniffer sniff to check against the PSR-x Coding Standard

Download files at

if you are using Xampp,

  1. unpack PSR-1 CodeSniffer rules under \xampp\php\PEAR\PHP\CodeSniffer\Standards\PSR (SPR or any directory will work)
  2. Go to Settings (CTRL-ALT-S) and search for "PHP Code Sniffer Validation", click the button Validate to force reload of rules from disk
  3. PSR is available in the list

PHPStorm 3.x / 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.

There is currently no plugin available The CodeSniffer can also be integrated easily as an external tool. PHPStorm will display the output in the console, including clickable 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)
  • "Paramaters":
    • --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
    • Optional 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 toolbar button with a nice Joomla! logo Icon-16-joomla.png.

References