PHPStan Baseline

When to use

• The user wants to adopt PHPStan on an existing legacy codebase that already has many type errors, without blocking on a full cleanup.
• The user wants to generate a PHPStan baseline to snapshot existing errors so a new level can pass without fixing everything first.
• The user wants to shrink the PHPStan baseline over time, or keep it from growing, as they pay down type debt.

When NOT to use

• Do not generate a baseline for a new or already-green codebase; fix the handful of errors directly instead of freezing them.
• Do not use a baseline to permanently silence a rule you never intend to fix; use a scoped ignoreErrors entry for a deliberate, documented exception.

Core guidance

• Generate the baseline with generate-baseline — Create the baseline with vendor/bin/phpstan analyse --generate-baseline, which writes a phpstan-baseline.neon listing every current error.
• Include the baseline from phpstan.neon — Add includes: [phpstan-baseline.neon] to your phpstan.neon so the baselined errors are ignored on every run and commit both files.
• Enforce zero new errors in CI, never regenerate to hide them — In CI run phpstan analyse (no --generate-baseline) so new errors fail the build; only regenerate the baseline in a deliberate, reviewed commit.

Quick recipe

1. Set the target level in phpstan.neon, then run vendor/bin/phpstan analyse --generate-baseline to snapshot current errors. (verify: A phpstan-baseline.neon file is written listing the existing errors.)
2. Add includes: [phpstan-baseline.neon] to phpstan.neon, then commit both files so the frozen errors apply everywhere. (verify: A fresh vendor/bin/phpstan analyse now exits 0.)
3. Run plain phpstan analyse in CI so new errors fail; as you touch legacy files, fix their baselined errors and regenerate so the baseline only shrinks. (verify: CI fails on a newly introduced error and the baseline count trends downward.)

Best practices

• When raising the analysis level, regenerate the baseline once to absorb the new level's pre-existing errors, then hold it steady until the next planned bump
• Keep parameters.reportUnmatchedIgnoredErrors: true (the default) so PHPStan flags baseline entries that no longer match, prompting you to regenerate and drop them
• Treat the baseline as debt to pay down: fix baselined errors in files you already touch, then regenerate so removed errors drop out and the file only shrinks

Anti-patterns

See references/anti-patterns.md.

Common mistakes

1. Baseline generated but never included — You run --generate-baseline, commit phpstan-baseline.neon, but analysis still reports all the old errors. Fix: Add includes: [phpstan-baseline.neon] to phpstan.neon and rerun the analysis.
2. Baseline entries drift when lines shift — Editing a baselined file shifts line numbers so a frozen error resurfaces or an unrelated one gets swallowed, producing confusing CI diffs. Fix: Regenerate the baseline after substantial edits to a legacy file, or fix that file's baselined errors while you are in it so the entries disappear cleanly.
3. Baseline file causes constant merge conflicts — A single large phpstan-baseline.neon conflicts on almost every branch because many PRs regenerate overlapping regions of it. Fix: Discourage per-PR regeneration (only regenerate on level bumps), or split the baseline per top-level directory via multiple included files to localize churn.

Version notes

• Baseline format and PHP 7.4 through 8.4 support (PHP >=7.4) — --generate-baseline writes a neon file by default; PHPStan can also emit PHP or JSON baselines via --generate-baseline=phpstan-baseline.php, and the feature works identically across PHP 7.4 through 8.4.
• reportUnmatchedIgnoredErrors defaults on in PHPStan 2.x (PHP >=7.4) — In PHPStan 2.x reportUnmatchedIgnoredErrors defaults to true, so baseline entries that no longer match cause a failure until you regenerate; older versions were more lenient about stale entries.

Security

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

Testing

• Activation and decision behavior are verified in eval/scenarios/phpstan/baseline.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: phpstan/getting-started