PHPStan

Last modified: 22 November 2021

PhpStorm 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 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 PHPStan on-the-fly are displayed as popup messages. When the tool is run in the batch mode, the errors and warnings are displayed in the Problems tool window. Each message has the phpstan prefix to distinguish it from PhpStorm internal inspections.

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

Prerequisites

Prior to integrating PHPStan in PhpStorm, 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 exec mode to avoid spawning additional containers.

    1. In the Settings/Preferences dialog (Ctrl+Alt+S), go to 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

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

Install PHPStan 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.

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/Preferences dialog (Ctrl+Alt+S), navigate to 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.

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

Configure PHPStan 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 Configure remote PHP interpreters or in Configure local PHP interpreters.

Choose a PHPStan script to use

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

  2. On the Quality Tools page that opens, expand the PHPStan area. From the Configuration list, choose the PHPStan 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 PHPStan 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 PHPStan because PhpStorm runs a script (phpstan.bat for Windows or phpstan 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/Preferences dialog, choose By default project interpreter.

Configure a local PHPStan script

  1. Download and install the PHPStan scripts.

    To check the PHPStan installation, switch to the installation directory and run the following command:

    phpstan --version

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

  2. Register the local PHPStan script in PhpStorm:

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

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

    • In the PHPStan dialog that opens, specify the location of the phpstan.bat or phpstan PHPStan executable in the PHPStan path field. Type the path manually or click the Browse button and select the relevant folder in the dialog that opens.

      To check that the specified path to phpstan.bat or phpstan ensures interaction between PhpStorm and PHPStan, 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 phpstan --version command. If validation passes successfully, PhpStorm displays the information on the detected PHPStan version.

  3. If necessary, in the Tool process timeout field, specify how long you want PhpStorm to wait for a result from PHPStan, whereupon the process is terminated to prevent excessive CPU and memory usage.

Configure a PHPStan script associated with a PHP interpreter

  1. In the Settings/Preferences dialog (Ctrl+Alt+S), go to 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. The PHPStan dialog opens showing the list of all the configured PHPStan 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.

  3. Click the Add button on the toolbar. In the PHPStan 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 Configure remote PHP interpreters.

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

  4. If necessary, in the Tool process timeout field, specify how long you want PhpStorm to wait for a result from PHPStan, whereupon the process is terminated to prevent excessive CPU and memory usage.

Configure PHPStan as a PhpStorm inspection

Configure 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, PhpStorm 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"
}

note

After PHPStan is initially configured, further modifications in composer.json will not affect the inspection configuration. To apply newer changes, reset the PHPStan configuration on the PHP |Quality Tools page of the Settings/Preferences dialog (Ctrl+Alt+S) and update project dependencies.

Configure the PHPStan inspection manually

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

    tip

    If you have installed PHPStan with Composer but the corresponding inspection is currently disabled, PhpStorm highlights its record in composer.json. Press Alt+Enter and use the provided Enable inspection quick-fix to enable the inspection and open the Inspections page.

    Enable the PHPStan inspection

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

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

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

    3. In the Level field, provide the desired Rule Level against which the PHPStan checks are performed. Note that if a configuration file is provided, PhpStorm relies on the level value specified in this file, and the Level field is ignored.

    4. In the Configuration file field, provide the path to the PHPStan configuration file.

    5. In the Autoload file, provide the path to the autoloader. Note that if a configuration file is provided, PhpStorm relies on the autoload-file value specified in this file, and the Autoload file field is ignored.

    6. In the Memory limit field, provide the maximum amount of RAM PHPStan is allowed to allocate. You can either provide an explicit integer value in bytes or use a shorthand notation (500M, 4G, and so on).

    note

    The Full project run (batch mode only) option is only applicable when running the inspection in batch mode. If selected, the entire project is included in the inspection run scope; otherwise, only the source roots are included.

Run PHPStan in the batch mode

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, PhpStorm suggests adding the file to the ignore list.

See also

Procedures

Reference