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.
- 1. Enable PHP Mess Detector integration in PhpStorm
- 2. Viewing PHPMD warnings and errors in the editor
- 3. (optional) Checking code styles for the entire project
- 4. (optional) Working with custom rulesets
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.
Use the Composer | Add dependency... context menu on your project:
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:
- Code Size Rules: contains a collection of rules that find problems related to code size.
- Controversial Rules: contains a collection of controversial rules.
- Design Rules: contains a collection of rules that find software design related problems.
- Naming Rules: contains a collection of rules about names - too long, too short, and so forth.
- Unused Code Rules: contains a collection of rules that find unused code.
- 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.
- From the Specify Inspection Scope dialog, click the ... button to open the available inspection profiles.
- In the toolbar, click Add to create a new Inspection Profile.
- Give the custom Inspection Profile a name and click OK.
- 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:
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:
- Install PHP Mess Detector using Composer.
- Enable PHP Mess Detector integration in PhpStorm.
- Configure the PHP Mess Detector validation inspection (specify inspection severity and select the rulesets that should be used).
- From Project Settings | Inspections, enable the Share Profile checkbox.
- 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.
- When using custom rulesets, make sure they are located under the project folder and that they are added to source control.