PHPStan Getting Started

When to use

• The user wants to choose or raise a PHPStan analysis level (0 through 10) for their code.
• The user wants to write or edit a phpstan.neon config to set paths, level, includes, or ignore rules.
• The user wants to install PHPStan and run static analysis on a PHP codebase for the first time.

When NOT to use

• Do not use PHPStan to enforce code style, spacing, or formatting; use a fixer such as PHP-CS-Fixer or PHP_CodeSniffer instead.
• Do not reach for PHPStan to verify runtime behavior or business logic; write unit or feature tests for that.

Core guidance

• Analyse your own source, not vendor — Point paths at your own directories (e.g. src, app, tests) and never add vendor to paths; PHPStan reads third-party code for context automatically.
• Keep level and paths in phpstan.neon, not CLI flags — Declare level and paths in a committed phpstan.neon (or phpstan.dist.neon) rather than passing --level and directories on the command line.
• Run analysis in CI and fail on a non-zero exit — Run vendor/bin/phpstan analyse in CI and treat its non-zero exit code as a build failure so new type errors cannot merge.
• Start at a low level and raise it gradually — Start analysis at level 0 (or level: max only on greenfield code), get a green run, then raise the level one step at a time and fix the new errors each step.

Quick recipe

1. Install the analyser with composer require --dev phpstan/phpstan. (verify: vendor/bin/phpstan --version prints a version number.)
2. Create phpstan.neon at the project root with parameters.level: 0 and parameters.paths: [src] (add tests if you analyse them). (verify: The file parses and lists your own source directories under paths.)
3. Run vendor/bin/phpstan analyse; once it is green, bump level by one, fix the new errors, and repeat until you reach your target level. (verify: The analyser exits 0 at the current level before you raise it.)

Best practices

• Pull in framework and library type extensions through the includes key in phpstan.neon (e.g
• When you must silence an error, add a specific ignoreErrors entry scoped by message regex and path, rather than lowering the level or ignoring broadly

Anti-patterns

See references/anti-patterns.md.

Common mistakes

1. Reflection or class-not-found errors from missing autoload — PHPStan reports "class not found" or reflection errors when it cannot autoload classes that are not covered by Composer's autoloader. Fix: Add the extra paths under scanFiles/scanDirectories in phpstan.neon, or make the classes loadable via composer dump-autoload, so PHPStan can resolve them.
2. Analysis dies with a memory-limit fatal — On large codebases the analyser can exhaust PHP's memory_limit and abort with a fatal before finishing. Fix: Raise the limit for the run with phpstan analyse --memory-limit=1G, or set a higher memory_limit in the CLI php.ini used by CI.
3. Stale result cache hides or invents errors — After changing config, PHP version, or extensions, a stale result cache can report errors that are already fixed or miss new ones. Fix: Run phpstan clear-result-cache (or delete the tmpDir) after changing the neon config, PHP version, or included extensions, then re-analyse.

Version notes

• Level 10 and level max in PHPStan 2.x (PHP >=7.4) — PHPStan 2.0 added analysis level 10, and level: max is an alias that always points at the current highest level (10 today); on PHPStan 1.x the top level was 9.
• phpstan.neon.dist and local override precedence (PHP >=7.4) — PHPStan auto-discovers phpstan.neon then falls back to phpstan.neon.dist; commit the shared config as phpstan.neon.dist and let developers add a gitignored phpstan.neon for local-only overrides.

Security

• Not applicable — no I/O, auth, or untrusted input.

Testing

• Activation and decision behavior are verified in eval/scenarios/phpstan/getting-started.yaml.

Additional resources

• references/anti-patterns.md
• references/core.md
• references/examples.md
• references/pitfalls.md
• references/recipes.md
• references/version-differences.md

Knowledge graph

Prerequisites: php/typed-properties
Related: testing/pest-basics