Fixing a Legacy PHP Codebase: PHPStan’s Baseline Generator

PHPStan is a static code analysis tool. It scans your code, trying to find errors that you wouldn’t usually trigger until runtime; calling a method that doesn’t exist. Or attempting to return a string value in a function with a int return type.

This is different than Laravel Pint, which I wrote about recently. Pint is a code linter, which is concerned about the style of your code (Go team tabs!).

Analyzing a New Codebase

Running PHPStan on a new code base is easier. You might have an error or two to clean up, but otherwise, you’re starting from a clean slate.

Analyzing a Legacy Codebase

The problem comes when you decide you need static code analysis on a legacy code base and you end up with thousands of errors.

You don’t want to create a single pull request that will attempt to solve all these errors in one shot. Nor do you want to wait until you’ve fixed all the errors before enabling PHPStan.

Starting from a Baseline

This is where the Generate Baseline feature is a lifesaver.

If you run

vendor/bin/phpstan analyze app/ -b

the output of your static code analysis is saved to a phpstan-baseline.neon file. You can add this baseline file to the “includes” section of your phpstan.neon file, all your existing errors will be ignored the next time you run the analyze command.

Hooray! With the baseline file, PHPStan will only tell you about errors relating to new or modified lines of code. This allows you to start enforcing the use of static code analysis right away.

How to deal with the ignored errors

You do want to eventually fix the errors in the existing code. To do this, modify your phpstan.neon file and comment out the include line for the baseline file. You could also create a separate phpstan-nobaseline.neon file and use it in the --configuration attribute to the analyze command if that’s easier. It would be nice if there was an --ignore-baseline flag, but there isn’t.

With the include file commented out, you see the full list of errors. Now you can:

1. Fix the errors
2. Regenerate the baseline file
3. Make sure the baseline file is included in the phpstan.neon file again.

Level Up

PHPStan rules come in different levels, with 0 being the least and 9 being the most strict.

If you’re upgrading a legacy codebase, use the baseline file and the rule levels to work your way up to a clean codebase. The first time you turn the baseline file off, only scan for level 0 errors.

vendor/bin/phpstan analyze app/ --level 0

Clean up those errors first. That might be it’s own pull request (or several of them). Once you have those done, run the analysis again at level 1, then 2, etc until you’ve slowly fixed your code.

Want to learn more?

I hope you find some value in PHPStan. I know I did. For some information, you can see their official docs here: https://phpstan.org/user-guide/getting-started