IntelliJ IDEA 2023.2 Help

PHP Mess Detector

In addition to built-in coding assistance, IntelliJ IDEA 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, and so on.

To use PHP Mess Detector from IntelliJ IDEA instead of command line, you need to register it in IntelliJ IDEA and configure it as a IntelliJ IDEA code inspection. Once installed and enabled in IntelliJ IDEA, 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 highlighted in the editor. When the tool is run in batch mode, the errors and warnings are displayed in the Problems tool window. Each message has the phpmd prefix to distinguish it from IntelliJ IDEA internal inspections.

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

Install the PHP plugin

This functionality relies on the PHP plugin, which you need to install and enable.

  1. Press Control+Alt+S to open the IDE settings and then select Plugins.

  2. Open the Marketplace tab, find the PHP plugin, and click Install (restart the IDE if prompted).


Prior to integrating PHP Mess Detector in IntelliJ IDEA, make sure the following prerequisites are met:

  • The directory containing the PHP engine executable must be added to the system path. This allows code quality tool scripts to execute calls to the system-wide PHP engine.

  • For Docker Compose-based remote interpreters, make sure to use docker-compose exec mode to avoid spawning additional containers.

    1. In the Settings dialog (Control+Alt+S), go to Languages & Frameworks | PHP.

    2. On the PHP page that opens, click the Browse button next to the CLI Interpreter list.

    3. In the CLI Interpreters dialog that opens, set the Lifecycle mode for the selected interpreter to Connect to existing container ('docker-compose exec') .

      docker-compose exec for PHP interpreter

Install and configure PHP Mess Detector

Install PHP Mess Detector with Composer

When you install PHP Mess Detector with Composer, IntelliJ IDEA automatically downloads the necessary scripts, registers them in the IDE, and, optionally, enables and configures the corresponding code inspection.

  1. Inside composer.json, add the phpmd/phpmd dependency record to the require or require-dev key. Press Control+Space to get code completion for the package name and version.

  2. Do one of the following:

    • Click the Install shortcut link on top of the editor panel.

    • If the Non-installed Composer packages inspection is enabled, IntelliJ IDEA will highlight the declared dependencies that are not currently installed. Press Alt+Enter and select whether you want to install a specific dependency or all dependencies at once.

Click the Settings button next to the package record in the composer.json editor gutter to jump to the corresponding Settings page and configure PHP Mess Detector manually.

Gutter icon for phpmd settings in composer.json

Reset PHP Mess Detector configuration

After PHP Mess Detector is initially configured, further modifications in composer.json will not affect the inspection configuration. To apply newer changes, reset the PHP Mess Detector configuration.

  1. In the Settings dialog (Control+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.

  3. In the PHP Mess Detector dialog that opens, empty the PHP Mess Detector path field.

    Empty PHP Mess Detector path field
  4. Update the project Composer dependencies by clicking Update on top of the composer.json editor panel. For more information, refer to Update dependencies.

IntelliJ IDEA will perform the PHP Mess Detector configuration anew and thus apply the changes in composer.json.

Configure PHP Mess Detector in IntelliJ IDEA

In Settings (Control+Alt+S) | Languages & Frameworks | PHP | Quality Tools | PHP Mess Detector, you can change the default PHP interpreter, set the path to a manually downloaded and installed PHP Mess Detector executable file, or add some options to be passed to PHP Mess Detector when running it in IntelliJ IDEA.

PHP Mess Detector settings

Enable PHP Mess Detector as an IntelliJ IDEA inspection

There are two ways to set up PHP Mess Detector as a IntelliJ IDEA inspection: automatically during PHP Mess Detector installation with Composer, or manually in IntelliJ IDEA's inspections settings.

Enable the PHP Mess Detector inspection with Composer

You can include the 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, IntelliJ IDEA 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.

  • 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" }

Enable PHP Mess Detector validation in Inspections settings

  1. In the Settings dialog (Control+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.

    Select PHP Mess Detector validation checkbox
  3. On the right-hand pane of the page, configure how IntelliJ IDEA handles the PHP Mess Detector inspection output:

    1. Scope: choose the scope to limit the inspection application to.

    2. Severity: choose the severity degree for the inspection. The selected value determines how seriously the detected discrepancies will be treated by IntelliJ IDEA and presented in the inspection results.

    3. Highlighting in editor: choose how the issues detected by the inspection are highlighted in the editor.

Share 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 an IntelliJ IDEA 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). For more information, refer to Configure profiles.

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

Run PHP Mess Detector in batch mode

  1. Go to Code | Inspect code.

  2. In the Specify Inspection Scope dialog that opens, select the inspection profile from the list, or click Configure to open the Inspections dialog and configure a new profile.

    You can also click Configure to check which fixes will be applied within the scope of the selected inspection profile, and make sure that the PHP Mess Detector validation inspection is enabled.

  3. View the inspection results in the Problems tool window. Errors and warnings reported by PHP Mess Detector are prefixed with phpmd to distinguish them from IntelliJ IDEA internal inspections.

Exclude files from PHP Mess Detector Validation inspection

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

  1. In the Settings dialog (Control+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 Close button.

Last modified: 05 September 2023