PHPStan — PHP Static Analysis Tool

Introduction

PHPStan finds bugs in PHP code without running it. It reads your codebase, understands types and control flow, and reports errors ranging from undefined variables to incorrect method calls. Its level-based approach lets teams adopt static analysis incrementally.

What PHPStan Does

• Analyzes PHP source files for type errors, undefined methods, and unreachable code
• Supports 10 strictness levels (0-9) for incremental adoption
• Understands PHPDoc annotations, generics, and conditional return types
• Provides a baseline feature to ignore existing errors while catching new ones
• Offers a plugin architecture for framework-specific extensions (Laravel, Symfony, Doctrine)

Architecture Overview

PHPStan parses PHP files using nikic/php-parser into an AST, then builds a type inference engine on top of it. Each rule registers against specific AST node types and receives rich type information. The analysis runs in a single pass per file with cross-file type resolution handled by a reflection layer that reads both source and compiled stubs.

Self-Hosting & Configuration

• Install via Composer as a dev dependency or use the PHAR distribution
• Create a phpstan.neon configuration file to set paths, level, and parameters
• Generate a baseline with phpstan analyse --generate-baseline for legacy projects
• Add to CI with vendor/bin/phpstan analyse --no-progress --error-format=github
• Use the tmpDir parameter to configure the cache directory for faster re-analysis

Key Features

• 10 rule levels for gradual strictness escalation from basic to strict
• Baseline file to track and ignore pre-existing errors
• Rich extension ecosystem with official packages for Laravel, Symfony, Doctrine, and PHPUnit
• Generic types and template support for advanced type checking
• Result cache for fast incremental analysis on large codebases

Comparison with Similar Tools

• Psalm — similar PHP static analyzer with a focus on security taint analysis; PHPStan has broader framework extension support
• Phan — another PHP analyzer that uses php-ast extension; PHPStan runs without native extensions
• PHP_CodeSniffer — enforces coding standards and formatting; PHPStan focuses on finding type errors and bugs
• Rector — automates refactoring and upgrades; PHPStan identifies issues but does not auto-fix code

FAQ

Q: How do I handle false positives? A: Use @phpstan-ignore-next-line comments for one-off cases, or generate a baseline file for bulk ignoring of legacy issues.

Q: Can PHPStan analyze a project without running it? A: Yes. PHPStan performs static analysis only. It never executes your PHP code.

Q: What PHP versions does PHPStan support? A: PHPStan runs on PHP 7.4+ and can analyze code targeting PHP 7.1 through 8.x by configuring the phpVersion parameter.

Q: How do I integrate PHPStan with Laravel? A: Install the larastan/larastan extension package and include it in your phpstan.neon file. It teaches PHPStan about Laravel facades, models, and collections.

Sources

• https://github.com/phpstan/phpstan
• https://phpstan.org/