IntelliJ IDEA 2021.3 Help

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 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 psalm prefix to distinguish it from IntelliJ IDEA internal inspections.

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

Make sure the PHP and Psalm plugins are enabled. The plugins are not bundled with IntelliJ IDEA, but they can be installed on the Settings/Preferences | Plugins page as described in Installing plugins from JetBrains repository. Once enabled, the plugins are available at the IDE level, that is, you can use them in all your IntelliJ IDEA projects.

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 exec mode to avoid spawning additional containers.

    1. In the Settings/Preferences dialog (Ctrl+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 Psalm

Psalm 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 Psalm 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 Psalm 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 vimeo/psalm dependency record to the require or require-dev section. Press Ctrl+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/Preferences button next to the package record in the composer.json editor gutter to jump to the corresponding Settings/Preferences page and configure Psalm manually.

Gutter icon for psalm settings in composer.json

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.

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

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

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

    Empty Psalm 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 Psalm configuration anew and thus apply the changes in composer.json.

Configure Psalm 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 Configuring Remote PHP Interpreters or in Configuring Local PHP Interpreters.

Choose a Psalm script to use

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

  2. On the Quality Tools page that opens, expand the Psalm area. From the Configuration list, choose the Psalm 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 Psalm 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 Psalm because IntelliJ IDEA runs a script (psalm.bat for Windows or psalm 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 Psalm script

  1. Download and install the Psalm scripts.

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

    psalm --version

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

    Psalm 3.17.1@8f2117914813e4dc89ff4ed372785ce93b902fd1

  2. Register the local Psalm script in IntelliJ IDEA:

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

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

    • In the Psalm dialog that opens, specify the location of the psalm.bat or psalm Psalm executable in the Psalm 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 psalm.bat or psalm ensures interaction between IntelliJ IDEA and Psalm, that is, the tool can be launched from IntelliJ IDEA and IntelliJ IDEA will receive problem reports from it, click the Validate button. This validation is equal to running the psalm --version command. If validation passes successfully, IntelliJ IDEA displays the information on the detected Psalm version.

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

Configure a Psalm script associated with a PHP interpreter

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

  2. On the Quality Tools page that opens, expand the Psalm area and click the Browse button next to the Configuration list. The Psalm dialog opens showing the list of all the configured Psalm 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 Psalm 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 Configuring Remote PHP Interpreters.

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

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

Configure Psalm as an IntelliJ IDEA inspection

Configure 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 the psalm 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" }

Configure the Psalm 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 Psalm validation.

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

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

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

    3. In the Configuration file field, provide the path to the Psalm configuration file. If the file is not present, IntelliJ IDEA displays the notification prompting you to create it.

      Psalm config not found notification
    4. Select the Show info checkbox to have Psalm report the errors that are at a lower level than the errorLevel specified in the configuration file. If the checkbox is not selected, such errors will be ignored.

    5. Select the Find unused code checkbox to have Psalm report the located unused code (including unused variables).

    6. Select the Find unused @psalm-suppress annotations checkbox to have Psalm report all unused @psalm-suppress annotations.

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:

Psalm validation inspection timeout error
  • 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

  1. From the main menu, select Code | Inspect code.

  2. Select the inspection profile from the list, or click the Browse button to configure a new profile in the Inspections dialog that opens. You can also click the Browse button to check, which fixes will be applied and make sure that the Psalm validation inspection is enabled.

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

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

  2. On the Quality Tools page that opens, expand the Psalm 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 Psalm process it again, select the file and click the Remove button.

    • To remove all the files from the list, click the Close button.

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 Ctrl+Space.

Providing a Psalm annotation

Types support

You can use the Psalm type annotations for pseudotypes such as numeric or scalar to provide IntelliJ IDEA with additional type information.

Providing a pseudotype Psalm annotation

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.

Providing a constants values union Psalm annotation

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.

Providing a template Psalm annotation
Last modified: 01 August 2022