Psalm
IntelliJ IDEA provides code quality check through integration with the Psalm tool, which validates your code for consistency against a set of validation rules.
To use Psalm 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 Psalm 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 the psalm
prefix to distinguish it from IntelliJ IDEA internal inspections.
Install the PHP and Psalm Support plugins
This functionality relies on the PHP and Psalm Support plugins that should be installed and enabled in your IDE.
The plugins are available only in IntelliJ IDEA Ultimate.
Press Control+Alt+S to open the IDE settings and select
.Switch to the Marketplace tab and use the search field to find the PHP and Psalm Support plugins.
Click Install and restart the IDE if prompted.
Prerequisites
Prior to integrating Psalm 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.In the Settings dialog (Control+Alt+S), go to .
On the PHP page that opens, click next to the CLI Interpreter list.
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 Psalm
Install Psalm with Composer
When you install Psalm with Composer, IntelliJ IDEA automatically downloads the necessary scripts, registers them in the IDE, and, optionally, enables and configures the corresponding code inspection.
Inside composer.json, add the
vimeo/psalm
dependency record to therequire
orrequire-dev
section. Press Control+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, 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 next to the package record in the composer.json editor gutter to jump to the corresponding Settings page and configure Psalm manually.
Reset Psalm configuration
After Psalm is initially configured, further modifications in composer.json will not affect the inspection configuration. To apply newer changes, reset the Psalm configuration.
In the Settings dialog (Control+Alt+S), navigate to .
On the Quality Tools page that opens, expand the Psalm area and click next to the Configuration list.
In the Psalm dialog that opens, empty the Psalm path field.
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 Psalm configuration anew and thus apply the changes in composer.json.
Configure Psalm in IntelliJ IDEA
When you install Psalm with Composer, IntelliJ IDEA automatically detects Psalm'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) | , you can change the default PHP interpreter, set the path to a manually downloaded and installed Psalm executable file, or add some options to be passed to Psalm when running it in IntelliJ IDEA.
Configuration: in this field, you can change the default PHP interpreter and path to the Psalm executable file.
To only change the interpreter, select the required item from the list of local and remote PHP interpreters configured in your project.
To change the path to the Psalm executable file, or both the interpreter and the path, click next to the Configuration list to open the Psalm dialog and edit the fields there as described on the Psalm Dialog reference page.
Show ignored files: use this setting to exclude files from Psalm validation inspection. For details, see the Quality Tools reference page.
Options: in this area, add the options to run Psalm as a IntelliJ IDEA inspection with. Edit the fields there as described on the Psalm reference page.
Enable Psalm as an IntelliJ IDEA inspection
There are two ways to set up Psalm as a IntelliJ IDEA inspection: automatically during Psalm installation with Composer, or manually in IntelliJ IDEA's inspections settings.
Enable the Psalm inspection with Composer
You can include the information on the Psalm 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 Psalm 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 psalm.xml or psalm.xml.dist default name.
In the
scripts
section of composer.json, add thepsalm
Psalm launch command into one of the leaf elements.Provide the
--config
argument and the path to the configuration file:"scripts": { "psalm": "vendor/bin/psalm --config=psalm.xml" }
Enable Psalm validation in Inspections settings
In the Settings dialog (Control+Alt+S), click Inspections under Editor.
On the Inspections page that opens, expand the node and select the checkbox next to Psalm validation.
On the right-hand pane of the page, configure how IntelliJ IDEA handles the Psalm 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.
Initialize Psalm caches
While the Psalm validation inspection can be run on a single file, Psalm will still make a pass on the entire project. On large projects, waiting for Psalm response when running it for the first time can exceed the limit specified in the Tool process timeout field in the Psalm dialog. In such cases, IntelliJ IDEA displays the error message:
Click the Init cache link to have Psalm make a pass on the entire project and generate caches in the configured cache directory. If you are using a remote interpreter, make sure to set the cache directory to the location, which is accessible from within the remote environment.
Click the Exclude from Psalm analysis link to add the current file to the ignored files list.
Run Psalm in the batch mode
From the main menu, select
.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 Psalm validation inspection is enabled.
View the inspection results in the Problems tool window. Errors and warnings reported by Psalm are prefixed with to distinguish them from IntelliJ IDEA internal inspections.
Exclude files from Psalm Validation inspection
When waiting for Psalm response exceeds the limit specified in the Tool process timeout field in the Psalm dialog, IntelliJ IDEA suggests adding the file to the ignore list.
In the Settings dialog (Control+Alt+S), navigate to .
On the Quality Tools page that opens, expand the Psalm 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 Psalm process it again, select the file and click .
To remove all the files from the list, click .
Use extended @psalm annotations
Besides regular PHPDoc comments, IntelliJ IDEA supports Psalm-specific annotations, which are used by Psalm for performing code analysis. When specifying an annotation, in most cases you can omit the @psalm-
part. To use code completion, press Control+Space.
Types support
You can use the Psalm type annotations for pseudotypes such as numeric
or scalar
to provide IntelliJ IDEA with additional type information.
When providing type definitions via the @psalm-param
or @psalm-var
tags, you can use the constants' values unions (|
) and wildcards (*
) for constants sharing a common prefix.
Generics support
With the @template annotations, you can introduce basic generics support in IntelliJ IDEA. Initial support covers a simple case of a function returning one of its parameters.