psalm

Static analysis tool for PHP type safety

TLDR

Analyze project

$ psalm

Analyze with specific level

$ psalm --level=[5]

Analyze specific file

$ psalm [src/File.php]

Initialize configuration

$ psalm --init

Generate baseline

$ psalm --set-baseline=[baseline.xml]

Show info-level issues

$ psalm --show-info=true

Output as JSON

$ psalm --output-format=json

Fix issues automatically

$ psalm --alter --issues=[MissingReturnType]

SYNOPSIS

psalm [--level n] [--set-baseline file] [--config file] [options] [paths]

psalm is a static analysis tool for PHP that finds bugs and enforces type safety. It understands PHP type hints and PHPDoc annotations.
Error levels range from 1 (strictest) to 8 (most permissive). Higher levels allow more potential issues, suitable for legacy codebases.
Configuration in psalm.xml defines analysis scope, excluded files, and issue severity. Project-specific settings enable gradual adoption.
Baselines record existing issues to ignore. New code must pass analysis while legacy problems can be addressed over time.
The alter mode automatically fixes certain issues like adding return types or parameter types. This accelerates migration to stricter typing.
Psalm understands complex PHP patterns including generics, union types, and template types through PHPDoc syntax.

PARAMETERS

--level N

Error level (1-8).

--config, -c FILE

Configuration file.

--init

Initialize psalm.xml.

--set-baseline FILE

Generate baseline file.

--use-baseline FILE

Use baseline file.

--ignore-baseline

Ignore baseline.

--show-info

Show info-level issues.

--output-format FMT

Output format (console, json, xml, etc.).

--alter

Modify files to fix issues.

--issues LIST

Issues to fix with --alter.

--threads N

Parallel analysis threads.

--memory-limit SIZE

Memory limit.

--clear-cache

Clear cache.

CONFIGURATION

psalm.xml (or psalm.xml.dist)

Project configuration file defining error level, analysis scope, excluded directories, plugin loading, and issue severity overrides. Created with --init.

baseline.xml

Baseline file recording existing issues to ignore, allowing strict analysis on new code while deferring legacy fixes. Generated with --set-baseline.

CAVEATS

Strict levels may be impractical for legacy code. Some PHP patterns are difficult to analyze. Memory usage scales with project size.

HISTORY

Psalm was created by Matthew Brown at Vimeo around 2016. It brought advanced static analysis to PHP, supporting features like generics before PHP had native support.