My PHPMD Configuration on PHPStorm

5 min readApr 29, 2022

Introduction

PHP Mess Detector is yet another one of those tools that help to keep the code base manageable and clean.

PHP Mess Detector applies certain rules to check the quality of the code. The list of rules can be found here .

This document is intended as a guide to initializing PHPMD rules on PHPStorm. So that the whole team is synchronized on the same rules.

Rulesets

The rulesets.xml file at the project root defines the rules that PHPMD should apply to the project code. In agreement with the team, we decided to start with a custom configuration.

<?xml version="1.0"?>
<ruleset name="Verso PHPMD rulesets"
         xmlns="http://pmd.sf.net/ruleset/1.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://pmd.sf.net/ruleset/1.0.0 http://pmd.sf.net/ruleset_xml_schema.xsd"
         xsi:noNamespaceSchemaLocation="http://pmd.sf.net/ruleset_xml_schema.xsd">
    <description>
        Stefano PHPMD rulesets
    </description>

    <rule ref="rulesets/unusedcode.xml" />
    <rule ref="rulesets/cleancode.xml">
        <exclude name="StaticAccess" />
        <exclude name="MissingImport" />
    </rule>
    <rule ref="rulesets/design.xml/ExitExpression" />
    <rule ref="rulesets/design.xml/EvalExpression" />
    <rule ref="rulesets/design.xml/GotoStatement" />
    <rule ref="rulesets/design.xml/DepthOfInheritance" />
    <rule ref="rulesets/design.xml/CouplingBetweenObjects" />
    <rule ref="rulesets/design.xml/DevelopmentCodeFragment" />
    <rule ref="rulesets/design.xml/EmptyCatchBlock" />
    <rule ref="rulesets/design.xml/CountInLoopExpression" />
    <rule ref="rulesets/design.xml/NumberOfChildren">
        <properties>
            <property name="minimum" value="2"/>
        </properties>
    </rule>

    <rule ref="rulesets/naming.xml/ShortMethodName" />
    <rule ref="rulesets/naming.xml/ConstructorWithNameAsEnclosingClass" />
    <rule ref="rulesets/naming.xml/ConstantNamingConventions" />
    <rule ref="rulesets/naming.xml/BooleanGetMethodName" />
    <rule ref="rulesets/naming.xml">
        <exclude name="ShortVariable" />
        <exclude name="LongVariable" />
        <exclude name="LongClassName" />
    </rule>

    <rule ref="rulesets/controversial.xml"/>

    <rule ref="rulesets/codesize.xml/NPathComplexity"/>
    <rule ref="rulesets/codesize.xml/ExcessiveMethodLength"/>
    <rule ref="rulesets/codesize.xml/ExcessiveClassLength"/>
    <rule ref="rulesets/codesize.xml/ExcessiveParameterList"/>
    <rule ref="rulesets/codesize.xml/TooManyMethods"/>
    <rule ref="rulesets/codesize.xml/ExcessivePublicCount" />
    <rule ref="rulesets/codesize.xml/ExcessiveClassComplexity" />
    <rule ref="rulesets/codesize.xml/CyclomaticComplexity">
        <priority>1</priority>
        <properties>
            <property name="reportLevel" value="7" />
        </properties>
    </rule>
</ruleset>

Customizing CleanCode Rules

<rule ref="rulesets/cleancode.xml">
    <exclude name="StaticAccess" />
    <exclude name="MissingImport" />
</rule>

Static Access

Although the use of static methods is generally not recommended, today static methods are widely used to create objects, for example in “factories”. The Symfony framework uses this technique several times. For this reason, I exclude the rule from our PHPMD.

Missing Import

The exclusion of this rule is motivated by the fact that, since PHP 5.3, for the inclusion of classes (internal or external) namespaces are used. But we use also many standard PHP functions. These must be imported using a backslash for two main reasons:

prefixing global or built in functions and constants with \ makes sure they are not over-ridden by declarations within the current namespace.
when calling it directly from the root namespace performance is considerably faster.

Customizing Design Rules

<rule ref="rulesets/design.xml/NumberOfChildren">
    <properties>
        <property name="minimum" value="2"/>
    </properties>
</rule>

For the same reasons that the keyword final should always be used, a class should not have too many children. The default value of 15 is excessive.
Here are the reasons for this rule:

It prevents an uncontrolled chain of inheritance.
It encourages composition.
It promotes the single responsibility principle.
It encourages developers to use public methods instead of extending the class to access protected methods.
It allows to modify the code without breaking the applications that use the class.

Customizing CodeSize Rules

<rule ref="rulesets/codesize.xml/CyclomaticComplexity">
    <priority>1</priority>
    <properties>
        <property name="reportLevel" value="7" />
    </properties>
</rule>

The only customization I applied for this set of rules is for the complexity of a method.

As stated in the PHPMD documentation , generally 1–4 is low complexity, 5–7 indicates moderate complexity, 8–10 is high complexity, and 11+ is very high complexity.

Personalization of Naming Rules

<rule ref="rulesets/naming.xml">
    <exclude name="ShortVariable" />
    <exclude name="LongVariable" />
    <exclude name="LongClassName" />
</rule>

Another customization concerns the class names of variables and methods. The naming should be as functional as possible and give a quick description of the role of the class, method or variable, regardless of the length of the name.
For this reason I prefer to have as much freedom as possible regarding the naming of my elements.

Setup in PHPStorm

1 ) Go to Editor → Inspections and select PHP Mess Detector validation

2) Unhook all the options, otherwise PHPStorm will not take into account our ruleset.xml file but its rules.

3) Add the ruleset.xml file in the Custom rulesets field

4) Click on the Mess Detector link or go directly to PHP → Quality Tools

5) Click in the three small dots of Mess Detector and fill in the path of our phpmd

How to use on PHPStorm

In the PHPStorm preferences (Editor → Inspections → PHP Mess Detector validation), you can choose the severity level of the PHPStorm indicator.

This way, PHPStorm will indicate errors by highlighting the part of the code that violates a certain rule.

For example this class does not respect all the rules defined in rulesets.xml:

To find out which rule is not respected, there are two ways to do it:

By hovering over the point indicated by PHPStorm with the cursor

2. By clicking on the icon at the top right of the IDE screen

The issues panel will then open with the list of all broken rules in the selected folder.

Conclusions

PHPMD is a great tool for finding parts of code that don’t conform to modern and strong programming standards.
In my opinion it also helps you improve your way of programming.
I recommend everyone to use it together with many other tools such as PHPStan, PHPCs-fixer, PSalm etc. Using one does not exclude the use of the others.