Using Psalm for Static Analysis

Run Psalm on PHP source and enrich native types with PHPDoc array shapes and value constraints.

What It Does

Initialize the analyzer and run it without cached results. Psalm array shapes document required fields and positive quantities.

Requirements and Compatibility

Use a supported PHP runtime and install any third-party tool or extension explicitly shown in the examples. Commands should be run from the project root unless stated otherwise.

Syntax, Inputs and Results

The examples separate configuration, the smallest working operation and a realistic follow-up task. Adapt file paths and dependency versions to your own project.

Example 1: Basic Use

Initialize the analyzer and run it without cached results.

composer require --dev vimeo/psalm
vendor/bin/psalm --init
vendor/bin/psalm --no-cache

Example 2: Another Case

Psalm array shapes document required fields and positive quantities.

<?php
/** @param array{sku: non-empty-string, qty: positive-int} $line */
function lineLabel(array $line): string {
    return $line["sku"] . " x" . $line["qty"];
}
echo lineLabel(["sku" => "K42", "qty" => 2]);

Practical Example

Set a project analysis scope and a documented error level.

<psalm errorLevel="4"><projectFiles><directory name="src" /></projectFiles></psalm>

For production, apply the compatibility and edge-case limits described below.

Important Behavior and Edge Cases

Review inferred types before suppressing findings and keep the project Psalm configuration committed.

Comparison with Related Functions and Tools

Subject	Key difference
Psalm vs PHPStan	Both provide static type checks but have distinct rule sets, type inference and configuration formats.

Common Beginner Mistakes

Mistake	Correct approach
Silencing diagnostics instead of fixing contracts	Annotate arrays and returns accurately; suppress only well-understood false positives.
Skipping the prerequisite of this specific workflow	Install or configure the named tool and confirm the example can actually run.
Ignoring edge conditions	Review inferred types before suppressing findings and keep the project Psalm configuration committed.

Key Takeaways

Run Psalm on PHP source and enrich native types with PHPDoc array shapes and value constraints.
Review inferred types before suppressing findings and keep the project Psalm configuration committed.
Keep application configuration, source code and validation tests under version control.

Use these examples as a starting point, then validate the result with the actual PHP build, dependencies and inputs used by your application.