Psalm — PHP Static Analysis for Finding Bugs and Security Issues

Introduction

Psalm is a PHP static analysis tool originally developed at Vimeo that catches type errors, detects security vulnerabilities through taint analysis, and identifies dead code. It infers types deeply across your codebase without requiring full annotation coverage.

What Psalm Does

• Finds type errors and incorrect method calls without running the code
• Performs taint analysis to detect SQL injection, XSS, and other security flaws
• Identifies unused code including dead methods, variables, and imports
• Provides auto-fix suggestions for common issues via Psalter
• Supports PHPDoc, native type declarations, and advanced generic types

Architecture Overview

Psalm parses PHP files into an AST, performs multi-pass type inference across the entire project, and checks inferred types against declared constraints. The taint analysis engine traces data flow from user input sources to sensitive sinks, flagging paths where unsanitized data reaches dangerous operations.

Setup & Configuration

• Install via Composer as a dev dependency
• Generate psalm.xml config with --init specifying error level 1-8
• Run incrementally on changed files using --diff for fast feedback
• Configure baseline file to suppress existing issues during adoption
• Integrate with CI pipelines using non-zero exit codes on new errors

Key Features

• Generics support with template annotations for type-safe collections
• Security-focused taint analysis covering OWASP top vulnerabilities
• Plugin system for framework-specific analysis like Laravel and Symfony
• Language server protocol support for real-time IDE feedback
• Psalter automated code fixer for bulk migrations and refactoring

Comparison with Similar Tools

• PHPStan — similar static analysis but Psalm has stronger taint analysis and security checking
• Phan — requires more annotations; Psalm infers types more aggressively
• Rector — focuses on automated refactoring; Psalm focuses on finding bugs
• PHP_CodeSniffer — checks style/formatting; Psalm checks logic and type correctness
• Infer — Meta's cross-language analyzer; Psalm provides deeper PHP-specific analysis

FAQ

Q: How do I adopt Psalm in a large legacy codebase? A: Use --init with a high error level (e.g., 5-8) and generate a baseline to suppress existing issues, then tighten gradually.

Q: Does Psalm support PHP 8.x features? A: Yes. Psalm supports enums, named arguments, fibers, intersection types, and other PHP 8.x features.

Q: Can Psalm analyze code that uses magic methods? A: Yes, via @method and @property PHPDoc annotations or custom plugins that inform Psalm about dynamic behavior.

Q: How fast is Psalm on large codebases? A: Psalm caches analysis results and supports diff mode, analyzing only changed files in seconds on subsequent runs.

Sources

• https://github.com/vimeo/psalm
• https://psalm.dev