PhpStorm 2018.3 Help

PHP Mess Detector

In addition to built-in coding assistance, PhpStorm provides checking the source code through integration with the PHP Mess Detector tool, which detects potential problems related to code size, inconsistency, unused code, violation of naming conventions, poor design, etc.

To use PHP Mess Detector from PhpStorm instead of command line, you need to register it in PhpStorm and configure it as a PhpStorm code inspection. Once installed and enabled in PhpStorm, the tool is available in any opened PHP file, and no additional steps are required to launch it. The on-the-fly code check is activated upon every update in the file thus making it easy to get rid of discovered problems.

Errors and warnings reported by PHP Mess Detector on-the-fly are displayed as pop-up messages. When the tool is run in the batch mode, the errors and warnings are displayed in the Inspection Results tool window. Each message has the phpmd prefix to distinguish it from PhpStorm internal inspections.

You can have predefined rules applied or define your own custom set of rules.

Before you start

Make sure the PHP plugin is enabled. The plugin is activated by default. If the plugin is disabled, enable it on the Plugins settings page as described in Managing Plugins.

Installing and configuring PHP Mess Detector

PHP Mess Detector scripts can be used as local scripts, the scripts associated with PHP interpreters, or scripts declared as project dependencies and installed via Composer, which is the preferable and recommended way.

Installing PHP Mess Detector with Composer

Before you start, make sure Composer is installed on your machine and initialized in the current project as described in Composer Dependency Manager.

When you install PHP Mess Detector with Composer, PhpStorm automatically downloads the necessary scripts and registers them in the IDE.

  1. On the context menu of composer.json, choose Composer | Manage Dependencies. Alternatively choose Tools | Composer | Manage Dependencies from the main menu.

  2. In the Manage Composer Dependencies Dialog that opens, select the phpmd/phpmd package from the Available Packages list, possibly using the search field.

    Choose the relevant version from the Version to install list.

  3. If necessary, expand the Settings hidden area and specify the advanced installation options. In the Command line parameters field, type the additional command line parameters. It is recommended to provide the --dev, option: the package in this case is added to the require-dev section of the composer.json file instead of the default require section.

  4. Click Install.

Configuring PHP Mess Detector manually

You can use the manually downloaded local PHP code quality tool scripts or scripts associated with PHP interpreters. There can be a number of local and remote PHP interpreters, the one specified on the PHP page of the Settings/Preferences dialog is considered Project Default. Learn more about configuring PHP interpreters in Configuring Remote PHP Interpreters or in Configuring Local PHP Interpreters.

Choose a PHP Mess Detector script to use

  1. In the Settings/Preferences dialog (Ctrl+Alt+S), navigate to Languages & Frameworks | PHP | Quality Tools.

  2. On the Quality Tools page that opens, expand the Mess Detector area. From the Configuration list,

    choose the PHP Mess Detector script:

    • To use the script associated with a specific remote PHP interpreter, choose the name of this interpreter.

    • To use a local script, choose Local. In this case the local PHP Mess Detector will be executed no matter which PHP interpreter - local or remote - is used in the project. Note that there can be only one Local configuration for PHP Mess Detector because PhpStorm runs a script (phpmd.bat for Windows or phpmd for Linux and macOS) that contains a path to a PHP engine.

    • To use the script associated with the default project interpreter, that is, the one chosen on the PHP page of the Settings dialog, choose By default project interpreter.

Configure a local PHP Mess Detector script

  1. Download and install the PHP Mess Detector scripts.

    To check the PHP Mess Detector installation, switch to the installation directory and run the following command:

    phpmd --version

    If the tool is available, you will get a message in the following format:

    PHPMD version <version>

    To have code checked against your own custom coding standard, create it. Store the rules and the ruleset.xml file that points to them in the rulesets root directory.

  2. Register the local PHP Mess Detector script in PhpStorm:

    • In the Settings/Preferences dialog (Ctrl+Alt+S), navigate to Languages & Frameworks | PHP | Quality Tools.

    • On the Quality Tools page that opens, expand the Mess Detector area and click the Browse button next to the Configuration list.

    • In the PHP Mess Detector dialog that opens, specify the location of the phpmd.bat or phpmd PHP Mess Detector executable in the PHP Mess Detector path field. Type the path manually or click the Browse button and select the path in the dialog that opens.

      To check that the specified path to phpmd.bat or phpmd ensures interaction between PhpStorm and PHP Mess Detector, that is, the tool can be launched from PhpStorm and PhpStorm will receive problem reports from it, click the Validate button. This validation is equal to running the phpmd --version command. If validation passes successfully, PhpStorm displays the information on the detected PHP Mess Detector version.

Configure a PHP Mess Detector script associated with a PHP interpreter

  1. In the Settings/Preferences dialog (Ctrl+Alt+S), navigate to Languages & Frameworks | PHP | Quality Tools.

  2. On the Quality Tools page that opens, expand the Mess Detector area and click the Browse button next to the Configuration list. The PHP Mess Detector dialog opens showing the list of all the configured PHP Mess Detector scripts in the left-hand pane, one of them is of the type Local and others are named after the PHP interpreters with which the scripts are associated. Click the Add button on the toolbar.

  3. In the PHP Mess Detector by Remote Interpreter dialog that opens, choose the remote PHP interpreter to use the associated script from. If the list does not contain a relevant interpreter, click the Browse button and configure a remote interpreter in the CLI Interpreters dialog as described in Configuring Remote PHP Interpreters.

    When you click OK, PhpStorm brings you back to the PHP Mess Detector dialog where the new PHP Mess Detector configuration is added to the list and the right-hand pane shows the chosen remote PHP interpreter, the path to the PHP Mess Detector associated with it, and the advanced PHP Mess Detector options.

Configuring advanced PHP Mess Detector options

PhpStorm lets you specify advanced PHP Mess Detector options and thus fine-tune the PHP Mess Detector process behavior depending on the configuration of your computer and the rule sets used.

  1. In the Settings/Preferences dialog (Ctrl+Alt+S), navigate to Languages & Frameworks | PHP | Quality Tools.

  2. On the Quality Tools page that opens, expand the Mess Detector area. In the Maximum number of messages per file field set the upper limit for the total number of messages to be reported for a file. All the messages above this limit will be rejected and PhpStorm will display the warning message at top of the editor tab or in the Inspection Results Tool Window after the inspection is performed.

  3. In the Tool process timeout field, specify how long you want PhpStorm to wait for a result from PHP Mess Detector, whereupon the process is killed to prevent excessive CPU and memory usage.

  4. If necessary, in the PHP Code Beautifier and Fixer Settings area provide the path to the PHP Code Beautifier and Fixer tool in the Path to phpcbf field. This will let you automatically fix many of the errors detected by PHP Mess Detector. If you install PHP Mess Detector with Composer, PHP Code Beautifier and Fixer will be detected and set up automatically.

Configuring PHP Mess Detector as a PhpStorm inspection

Configure the PHP Mess Detector inspection

  1. In the Settings/Preferences dialog (Ctrl+Alt+S), click Inspections under Editor.

  2. On the Inspections page that opens, expand the PHP | Quality tools node and select the checkbox next to PHP Mess Detector validation.

  3. On the right-hand pane of the page, configure the PHP Mess Detector tool using the controls in the Options area:

    • From the Severity list, choose the severity degree for the PHP Mess Detector inspection. The selected value determines how serious the detected discrepancies will be treated by PhpStorm and presented in the inspection results.

    • From the Scope list, choose the scope to limit the inspection application to.

    • Appoint the rules to apply.

      • To use predefined rules, in the Options area, select the checkboxes next to the validations to be performed.

      • To use a custom ruleset:

        1. Create and save one or several ruleset files. A valid ruleset file is an .xml file that contains the <ruleset> root element with the name attribute. For more details on custom rulesets, see http://phpmd.org/documentation/creating-a-ruleset.html.

        2. In the Custom rulesets area, click Add button and select the relevant rule definition file in the dialog box that opens. When you click OK, a new item is added to the Custom rulesets list, where the Name field shows the ruleset name retrieved from the attribute name within the <ruleset> tag and the File field shows the location of the selected ruleset file.

Configuring the PHP Mess Detector inspection with Composer

You can include information on the default and custom PHP Mess Detector rulesets inside the scripts section of composer.json. When you install or update project dependencies, the specified rulesets will be detected and the PHP Mess Detector validation inspection will be enabled automatically.

If no ruleset is specified in the scripts section of composer.json, PhpStorm will additionally check the project root to locate the ruleset with the phpmd.xml default name. If the file is present, it will be automatically selected as the inspection's Custom ruleset.

Configure the PHP Mess Detector inspection with Composer

  • In the scripts section of composer.json, add the phpmd PHP Mess Detector launch command into one of the leaf elements.

    Provide the names of the built-in standards or the paths to custom rulesets as the arguments to denote the coding standards used.

    For example, adding the following record will select the Codesize and Controversial built-in rulesets, as well as the custom ruleset defined in the /my/src/custom_ruleset.xml file:

    "scripts": { "phpmd": "phpmd codesize,controversial,/my/src/custom_ruleset.xml" }

Sharing a custom coding style with the team

  1. Put the root directory of your coding standard under the project root.

  2. Configure PHP Mess Detector as a PhpStorm inspection.

  3. Appoint your coding standard.

  4. Make sure that a project profile is selected at the top of the Inspections page. Such profiles are saved in a particular project's .idea directory (for example, $PROJECT_DIR/.idea/inspectionProfiles). See Customizing Profiles for details.

  5. On the Version Control page of the Settings/Preferences dialog, make sure that the .idea directory is put under version control.

Running PHP Mess Detector in the batch mode

  1. Run the inspection, by choosing Code | Inspect code on the main menu. Specify the inspection scope and profile.

  2. View the inspection results in the Inspection Results Tool Window. Errors and warnings reported by PHP Mess Detector are prefixed with phpmd to distinguish them from PhpStorm internal inspections.

Excluding files from PHP Mess Detector inspection

When waiting for Mess Detector response exceeds the limit specified in the Tool process timeout field in the Mess Detector dialog, PhpStorm suggests adding the file to the ignore list.

Manage ignored files

  1. In the Settings/Preferences dialog (Ctrl+Alt+S), navigate to Languages & Frameworks | PHP | Quality Tools.

  2. On the Quality Tools page that opens, expand the Mess Detector area and click the Show ignored files link.

    • To add a file, click the Add button and locate the desired file in the dialog that opens.

    • To delete a file from the list and have Mess Detector process it again, select the file and click the Remove button.

    • To remove all the files from the list, click the Clean the list button the Close button.

Last modified: 18 March 2019

See Also