Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Update xml format name for coverage
Wiki Markup
{iframe:src=http://update.sonarsource.org/plugins/php-confluence.html|width=700|height=250350|frameborder=0}
Your browser does not support iframes.
{iframe}

...

The plugin enables analysis of PHP projects source code with SonarQube.

It is compatible with the Issues Report plugin to run pre-commit local analysis.

It relies on well-known external tools: PHPUnit, PHP Depend, PHPMD and PHP CodeSniffer.

Installation

  1. Install the PHP Environment
  2. Install the plugin through the Update Center or download it into the SONARQUBE_HOME/extensions/plugins directory
  3. Restart the SonarQube server

 Pure PHP files and mixed HTML / PHP files can be analyzed.

Since version 2.1

You can check compliance with PHP coding standards:

  • PSR-2: the quality profile of this name contains the rules to be PSR-2 compliant.

 

Info
titleSince version 2.0

Dependency on external tools has been removed: i.e PHPDepend, PHPCodeSniffer, PHPMD, PHPUnit.

It means that the plugin relies only on the SonarQube rule engine; there is no import of external rule engine results. (PHPUnit reports can still be imported.)

Many PHPMD rules are now offered natively by the plugin. If you think that the plugin is missing some "must have" rules, you are very welcome to send your suggestions to user@sonar.codehaus.org.

Include Page
Include - Plugin Installation
Include - Plugin Installation

Usage

Run an Analysis with the SonarQube Runner (Recommended method)

...

A sample project is available on GitHub that can be browsed or downloaded: /projects/languages/php/php-sonar-runner.

You can also have a look at the the SonarQube Runner documentation page to  to define a multi-module PHP project.

...

Maven and Ant can also be used to launch analysis on PHP projects.

Advanced Settings

Disabling or enabling external tools on demand

It is possible to disable each external tool. By default, all the external tools are enabled.

Code Block
languagebash
langxml
sonar.phpPmd.skip=true
sonar.phpCodesniffer.skip=true
sonar.phpDepend.skip=true    # Deactiving the PHP Depend plugin is highly discouraged since all the basic metrics rely on it.
sonar.phpUnit.skip=true
sonar.phpUnit.coverage.skip=true

Configuring PHPUnit to be run by SonarQube

To configure the execution of PHPUnit, it is recommended to create a configuration file and set the path to this file with the sonar.phpUnit.configuration property.

If a configuration file is not used, the following property can be set to configure the execution of PHPUnit:

Key

Default value

Description

sonar.phpUnit.ignore.configuration

 false

If true, PHPUnit will ignore any phpunit.xml file for launching the unit tests.
If false, PHPUnit will use any existing phpunit.xml file in the running directory.

sonar.phpUnit.mainTestClass

 

The project main test file including the relative path, ie: "/source/tests/AllTests.php". If not present, PHPUnit will look for phpunit.xml file in the test directory.

sonar.phpUnit.filter

 

Ignore the unit tests files matching this pattern.

sonar.phpUnit.bootstrap

 

Use this bootsrap file to initialize the unit tests.

sonar.phpUnit.analyze.test.directory

 true

If true, it will append test directory to PHPUnit. This will make PHPUnit look for test cases inside this directory. If several directories are defined as test directories, a phpunitRANDOM.xml file will be generated and passed to phpunit --configuration=. This generated file will contain all files inside the test directories.

sonar.phpUnit.group Only runs tests from the specified group(s).
sonar.phpUnit.loader To specify which TestSuiteLoader implementation to use.

Unit Tests and Code Coverage

To display unit test execution and code coverage data:

  1. Prior to the SonarQube analysis, execute your unit tests and generate a report in Clover XML format (execution + code coverage).
  2. Import these reports while running the SonarQube analysis by setting the:
    •  sonar.php.coverage.reportPath property to the path to the PHPUnit code coverage report file. The path may be either absolute or relative to the project base directory.
    •  sonar.php.tests.reportPath property to the path to the PHPUnit unit test execution report file. The path may be either absolute or relative to the project base directory.

A sample project is available on GitHub that can be browsed or downloaded/projects/languages/php/php-sonar-runner-unit-tests.

Reusing existing reports

To reuse existing reports from PHP Depend, PHPUnit, etc.:

  1. Set the sonar.<external_tool>.analyzeOnly property to true
  2. Set the path to the report in sonar.<external_tool>.reportPath. Path is relative to the base directory (where you for a mono-module project...
Code Block
languagebash
langxml
#PHPMD
sonar.phpPmd.analyzeOnly=true
sonar.phpPmd.reportPath=path/to/myPmdReport.xml 
 
#PHP CodeSniffer
sonar.phpCodesniffer.analyzeOnly=true
sonar.phpCodesniffer.reportPath=path/to/myCodeSnifferReport.xml
 
#PHP Depend
sonar.phpDepend.analyzeOnly=true
sonar.phpDepend.reportPath=path/to/myPhpDependReport.xml
sonar.phpDepend.reportType=summary-xml    #Type of report generated by PHP Depend. Valid values: summary-xml (default), phpunit-xml
 
#PHPUnit
sonar.phpUnit.analyzeOnly=true
sonar.phpUnit.reportPath=path/to/myPhpUnitReport.xml
sonar.phpUnit.coverage.reportPath=path/to/myCoverageReport.xml

Excluding files

Most of the time, using the exclusion properties will be enough to exclude files from being reported by SonarQube. However, there might be some cases where you really want to exclude files from being analyzed by an external tool (may it be PHP CodeSniffer,  PHPMD or PHP Depend) because:

  • a file is badly written and the tool is crashing when analyzing it, thus preventing SonarQube from completing the analysis
  • a large number of files must be excluded and there's no need for the external tools to spend time analyzing files that won't be reported in SonarQube

For these specific cases, you should use the sonar.xxxx.argumentLine property of the external tool to manually define exclusions. For instance, for PHP CodeSniffer, you would add the following property:

Code Block
sonar.phpCodesniffer.argumentLine=--ignore=Database/*    # on Linux, would be --ignore=Database\* on Windows

This would tell PHP CodeSniffer to ignore every PHP file located in the Database folder.

Note
titleBe carefull!

When specifying exclusions directly for each tool, you should also consider setting the sonar.exclusions property accordingly. Otherwise, you may have files with incomplete analysis.

FAQ

See PHP FAQ.

Metrics

See Metrics documentation page.

Extending Coding Rules

See the tutorial to extend coding rules with PHP CodeSniffer and/or PHPMD.

Roadmap

  1. PHP 1.2 - short-term activity (see the JIRA open tickets)
    1. Improve the PHP CodeSniffer rule repository (adding missing parameters, descriptions, ...)
    2. Work on the "Sonar Way", PEAR and Zend profiles (<= for PHP gurus! (wink) )
  2. PHP 2.0 - mid-term activity
    1. Handle multiple files with the same name
    2. Consider root folders as "Projects"
    3. Non structured PHP files
    4. If it turns out that those tickets are technically difficult/long to implement, then they can be postponed

Release Notes

Version 2.0

The PHP plugin does not rely anymore on external tools.