PHPStan

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 docker-compose 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 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') .

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.

When you install PHPStan with Composer, PhpStorm automatically downloads the necessary scripts, registers them in the IDE, and, optionally, enables and configures the corresponding code inspection.

Inside composer.json, add the phpstan/phpstan dependency record to the require or require-dev section. Press Ctrl+Space to get code completion for the package name and version.
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, PhpStorm 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 next to the package record in the composer.json editor gutter to jump to the corresponding Settings/Preferences page and configure PHPStan manually.

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.

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 next to the Configuration list.
In the PHPStan dialog that opens, empty the PHPStan path field.
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

In the Settings/Preferences dialog (Ctrl+Alt+S), navigate to PHP | Quality Tools.
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

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:
Register the local PHPStan script in PhpStorm:
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 next to the Configuration list.
3. 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 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.
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

In the Settings/Preferences dialog (Ctrl+Alt+S), go to PHP | Quality Tools.
On the Quality Tools page that opens, expand the PHPStan area and click 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.
Click 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 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.
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" }

Configure the PHPStan inspection manually

In the Settings/Preferences dialog (Ctrl+Alt+S), click Inspections under Editor.
On the Inspections page that opens, expand the PHP | Quality Tools node and select the checkbox next to PHPStan validation.
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.
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).
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

From the main menu, select Code | Inspect code.
Select the inspection profile from the list, or click to configure a new profile in the Inspections dialog that opens. You can also click to check, which fixes will be applied and make sure that the PHPStan validation inspection is enabled.
Use the Full project run (batch mode only) option to select whether the entire project or only its source roots are included in the inspection run scope.
View the inspection results in the Problems tool window. Errors and warnings reported by PHPStan are prefixed with to distinguish them from PhpStorm internal inspections.

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.

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 Show ignored files link.
- To add a file, click 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 .
- To remove all the files from the list, click .

Last modified: 21 February 2023