Skip to end of metadata
Go to start of metadata


PhpStorm comes with many inspections that help us analyze and improve the quality of our codebase. Additional inspections can be run on a PHP project using PHP Mess Detector (PHPMD). In this tutorial, we'll see how we can run these additional checks in PhpStorm and what value they can add to our development workflow.

PHP Mess Detector, or PHPMD in short, is a tool which can check PHP source code for potential problems. Just like PhpStorm's inspections, PHPMD can detect possible bugs, suboptimal code, unused parameters and so on. In addition to these, PHPMD contains several rules that check for complexity of code and will tell us if we should rewrite our code into something that is more maintainable. All these checks are integrated nicely in PhpStorm.


To make use of PHP Mess Detector, we first have to install it on our system.

Installing via Composer

A Composer package for PHP Mess Detector is available. A dependency can be added to composer.json using Composer Support in PhpStorm or manually. Composer will install PHP Mess Detector under the following path in your project: ./vendor/bin/phpmd and ./vendor/bin/phpmd.bat.

 Using Composer support in PhpStorm...

Use the Composer | Add dependency... context menu on your project:

 Manually editing composer.json...

Add the following to the composer.json file:

Installing via PEAR

Another way to install PHP Mess Detector is by using PEAR. Note we have to discover some additional channels in order to be able to download all dependencies:

This will install the PHP Mess Detector classes into our PEAR installation folder (for example C:\PHP\5.5\pear\PHP\PMD.php and will create a bash / batch script in the PHP installation folder (for example C:\PHP\5.5\phpmd and C:\PHP\5.5\phpmd.bat). Note that since PHP Mess Detector depends on pdepend, this executable is also installed.

1. Enable PHP Mess Detector integration in PhpStorm

1.1. Specifying the path to PHP Mess Detector

Through Project Settings | PHP | Mess Detector, we can specify the path to PHP Mess Detector, as well as some additional options (such as timeout) or files to be ignore when running rulesets.

1.2. Configure PHP Mess Detector as a PhpStorm inspection

Once PhpStorm knows the path to the PHP Mess Detector executable, we can configure it as a PhpStorm inspection through Project Settings | Inspections and then enabling the PHP Mess Detector validation inspection.

We can configure several additional parameters:

  • Severity: the severity of the inspection that will be shown in PhpStorm. This defaults to Weak warning; in the screenshot above we bumped it up to be a Warning instead.
  • Various rules that can be enabled:
  • Custom rulesets can be enabled as well. For example we can create a custom ruleset containing only rules we want to enable for our current project.

2. Viewing PHPMD warnings and errors in the editor

Results of running the PHP Mess Detector validation inspection will immediately be visible in the editor when opening a PHP file. Just like regular PhpStorm inspections, warnings and errors that are captured by PHP Mess Detector will be shown in the right gutter and as tooltips inside our code:

3. (optional) Checking code styles for the entire project

We can scan our entire codebase with PHP Mess Detector at once and get a grip on what the quality of the project's code is. Using the Code | Inspect code menu, we can let PhpStorm run the PHP Mess Detector validation on all files in our project (or on a subset). We will have to specify the inspection profile to use, which defaults to the inspection profile that is active for the current project.

In the screenshot above, I have created a custom inspection profile which will only run PHP Mess Detector and skips all other PhpStorm inspections so that the results list would not be too overwhelming. Note that we could just run the default inspection profile and filter the results afterwards.

 (optional) Creating a custom inspection profile...
  1. From the Specify Inspection Scope dialog, click the ... button to open the available inspection profiles.
  2. In the toolbar, click Add to create a new Inspection Profile.
  3. Give the custom Inspection Profile a name and click OK.
  4. Disable all inspections that are not required, and enable the ones that are.

Once PhpStorm and PHP Mess Detector finish running their rulesets, the inspection results will be shown. Warnings and errors found by PHP Mess Detector will be listed, grouped by folder. Clicking a warning on the left will display details on the right.

Using the toolbar on the left, we can change filtering and grouping options, as well as export the inspection results as XML or HTML.

4. (optional) Working with custom rulesets

PHP Mess Detector comes with several rulesets, but sometimes it may make sense to create our own ruleset. Rulesets can contain existing rules as well as new ones. We can create a custom ruleset containing only the PHPMD rules that we want to enable or that contain custom rules we created for our project.

4.1. Creating custom rulesets

Custom rulesets are XML files that reference any of the existing PHPMD rules or custom rules that we create based on the PHPMD abstract syntax tree.

The following is an example of a custom ruleset that only calculates cyclomatic complexity and uses different thresholds for warning us about complex code. We can save it as myrules.xml in our project.

Please refer to the PHPMD documentation for more information on creating a custom ruleset.

4.2. Enabling custom rulesets

In the previous step, we created myrules.xml containing a custom rule configuration. We can enable this custom ruleset through Project Settings | Inspections, enabling the PHP Mess Detector validation inspection and configuring the custom rulesets to use:

The ruleset we created contained the CyclomaticComplexity rule. This rule gives us an indication on how complex our code is and how maintainable (or not) it will be. Complexity is determined by the number of decision points in a method (if/else/while/for/case) plus one for the method entry. In general, lower complexity is better. The default Code Size Rules ruleset specified the threshold for complexity is > 11. In our example, we configured it to be > 4 so that we get a warning about our code's complexity much sooner:


PHPMD ships with a custom ruleset that can be enabled using the above technique: ./vendor/phpmd/phpmd/src/main/resources/rulesets/cleancode.xml. It contains rules that enforce a clean code base applying rules from SOLID and object calisthenics.

4.3. Sharing PHPMD configuration and custom rulesets with the team

When working in a team, it is best to all apply the same set of PhpStorm inspections and PHP Mess Detector rules. Sharing PHPMD configuration and rulesets with the team can be done by configuring it once and adding some configuration files to the VCS that is shared by the team:

  1. Install PHP Mess Detector using Composer.
  2. Enable PHP Mess Detector integration in PhpStorm.
  3. Configure the PHP Mess Detector validation inspection (specify inspection severity and select the rulesets that should be used).
  4. From Project Settings | Inspections, enable the Share Profile checkbox.
  5. Make sure the .idea\inspectionProfiles folder is added to source control so that team members have the same configuration when they pull the latest changes.
  6. When using custom rulesets, make sure they are located under the project folder and that they are added to source control.

  • No labels