IntelliJ IDEA 2023.1 Help

PHPStan

IntelliJ IDEA provides code quality check through integration with the PHPStan tool, which validates your code for consistency against a set of validation rules.

To use PHPStan from IntelliJ IDEA instead of command line, you need to register it in IntelliJ IDEA and set it up 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 PHPStan on-the-fly are highlighted in the editor. When the tool is run in the batch mode, the errors and warnings are displayed in the Problems tool window. Each message has a phpstan prefix to distinguish it from IntelliJ IDEA internal inspections.

PHPStan integration is implemented via the open-source PHPStan plugin. This plugin is bundled with IntelliJ IDEA and is enabled by default.

Install the PHP and PHPStan Support plugins

This functionality relies on the PHP and PHPStan Support plugins that should be installed and enabled in your IDE.

The plugins are available only in IntelliJ IDEA Ultimate.

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

  2. Switch to the Marketplace tab and use the search field to find the PHP and PHPStan Support plugins.

  3. Click Install and restart the IDE if prompted.

Prerequisites

Prior to integrating PHPStan 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 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 PHPStan

Install PHPStan with Composer

When you install PHPStan 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 phpstan/phpstan dependency record to the require or require-dev section. 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 PHPStan manually.

Gutter icon for phpstan settings in composer.json

Reset PHPStan configuration

After PHPStan is initially configured, further modifications in composer.json will not affect the inspection configuration. To apply newer changes, reset the PHPStan 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 PHPStan area and click the Browse button next to the Configuration list.

  3. In the PHPStan dialog that opens, empty the PHPStan path field.

    Empty PHPStan path field
  4. Update the project Composer dependencies by clicking Update on top of the composer.json editor panel. See Update dependencies for details.

IntelliJ IDEA will perform the PHPStan configuration anew and thus apply the changes in composer.json.

Configure PHPStan in IntelliJ IDEA

When you install PHPStan with Composer, IntelliJ IDEA automatically detects PHPStan's executable file in the vendor/bin folder and sets the PHP interpreter configured in the system path to run it.

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

PHPStan settings

Enable PHPStan as an IntelliJ IDEA inspection

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

Enable the PHPStan inspection with Composer

You can include the information on the PHPStan configuration file inside the scripts section of composer.json. When you install or update project dependencies, the specified configuration file will be detected and the PHPStan validation inspection will be enabled automatically.

If no configuration file is specified in the scripts section of composer.json, IntelliJ IDEA will additionally check the project root to locate the ruleset with the phpstan.neon or phpstan.neon.dist default name.

  • In the scripts section of composer.json, add the phpstan PHPStan launch command into one of the leaf elements.

    Provide the -c argument and the path to the configuration file:

    "scripts": { "phpstan": "vendor/bin/phpstan -c phpstan.neon" }

Enable PHPStan 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 PHPStan validation.

    Select PHPStan validation checkbox
  3. On the right-hand pane of the Inspections page, configure how IntelliJ IDEA shall handle the PHPStan inspection output:

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

    • 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.

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

Run PHPStan in the batch mode

  1. From the main menu, select 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 PHPStan validation inspection is enabled.

  3. View the inspection results in the Problems tool window. Errors and warnings reported by PHPStan are prefixed with phpstan:: to distinguish them from IntelliJ IDEA internal inspections.

    PHPStan inspections list

Exclude files from PHPStan Validation inspection

When waiting for PHPStan response exceeds the limit specified in the Tool process timeout field in the PHPStan 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 PHPStan 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 PHPStan 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: 21 June 2023