Psalm

Psalm is a static analysis tool for PHP, built and open-sourced by Vimeo, that performs deep type inference across a codebase to catch bugs — null dereferences, mismatched types, unreachable code, undefined variables — without executing the program. It supports gradual typing, so it can analyze both strictly-typed modern PHP and legacy code with little or no type coverage, escalating strictness as a project’s @psalm-* annotations improve over time.

Beyond conventional bug-finding, Psalm includes a taint-analysis mode that traces untrusted input from sources (like $_GET) to dangerous sinks (like eval or SQL queries) to flag potential security vulnerabilities such as SQL injection and XSS. It ships with a Language Server Protocol implementation for real-time IDE feedback, an automated refactoring tool (psalter), and a large plugin ecosystem — including framework-specific plugins for Laravel, Symfony, and PHPUnit — making it one of the two dominant PHP static analyzers alongside PHPStan.

What You Get

• A configurable static type checker with gradual-typing support, so analysis strictness can ramp up incrementally on legacy codebases
• Taint analysis mode that tracks untrusted data flow from request input to security-sensitive sinks
• psalter, an automated code-fixing tool that applies safe fixes for a subset of detected issues
• A Language Server Protocol server for real-time inline diagnostics in VS Code, PhpStorm, and other LSP-aware editors
• An extensible plugin API used by the wider ecosystem for framework- and library-specific type stubs (Laravel, Symfony, PHPUnit, and more)

Common Use Cases

• Gating pull requests in CI so type errors and null-safety violations are caught before merge
• Introducing static typing incrementally to a large legacy PHP codebase using Psalm’s baseline and gradual-strictness features
• Running taint analysis to catch SQL injection, XSS, and command-injection risks introduced by unsanitized user input
• Wiring the Psalm language server into an editor for live type-error feedback while writing PHP
• Auto-fixing a class of mechanical issues across a codebase with psalter instead of manual find-and-replace

Under The Hood

Architecture — Psalm is organized around a Codebase object that indexes every file in a project (Storage/ classes cache class, method, and property signatures), a Context object that tracks the inferred type of every variable at each point in a function as statements are walked, and an Issue/ hierarchy of over a hundred typed problem classes that are emitted via IssueBuffer and rendered through pluggable Report formatters (console, JSON, GitHub annotations, checkstyle XML). Analysis is parallelized across files using amphp/parallel worker processes for large codebases. Tech Stack — PHP 8.1–8.5, built on nikic/php-parser for AST generation, amphp/amp and amphp/parallel for concurrent multi-process analysis, symfony/console for the CLI, felixfbecker/language-server-protocol plus danog/advanced-json-rpc for the LSP server, and composer/semver for dependency-aware plugin compatibility checks. Code Quality — A ~50MB, multi-thousand-file PHP codebase (99.95% PHP) with a large PHPUnit test suite run via paratest for parallel execution, a committed psalm-baseline.xml (Psalm self-analyzes and suppresses its own known-acceptable findings), and strict phpcs style enforcement; the project has run for a decade with 465 contributors and 15k+ commits, reflecting mature engineering discipline. API Design — The plugin system (Plugin/ and PluginRegistrationSocket) exposes clean hook interfaces (after-method-call, after-expression, stub-file registration) that third-party plugins like psalm/plugin-phpunit build on, and the CLI itself favors a single psalm entrypoint with an XML config file (psalm.xml) over sprawling flags, keeping day-to-day usage simple despite the tool’s internal complexity.