Get "PHP 8 in a Nuthshell" (Now comes with PHP 8.3)
Amit Merchant

Amit Merchant

A blog on PHP, JavaScript, and more

Statically analysing your PHP code using PHPStan

The great thing about statically typed languages, like Java, C#, Go, Swift, etc. is that they can be analysed by the compiler itself. This means, if you’re using a statically typed language, you can catch a lot of errors at compile-time itself.

TypeScript is a great example of this. It’s a statically typed language that compiles down to JavaScript. And it can catch a lot of errors at compile-time itself.

This is not the case with dynamically typed languages like PHP, Python, etc. where you can only catch errors at runtime. You don’t have the luxury of catching errors at compile-time.

Luckily, there are tools that can help you catch errors at compile-time in PHP. One such tool is PHPStan. I’ll give you a primer on PHPStan in this article.

What is PHPStan?

PHPStan is a static analysis tool for PHP that can help you find bugs in your code without actually running it. It can catch whole classes of bugs even before you write tests for the code and make it robust enough to run in production.

It can also find bugs that are not easy to spot by just looking at the code or you might overlook them unintentionally like an if condition that always evaluates to true or a variable that is never used.

And that means you’ll be able to ship your code with confidence you’ve never had before.

PHPStan spots these bugs primarily based on how good you’ve type-hinted your code or documented your code using PHPDoc that looks like this.

 * @param Foo $param
 * @return Bar
function foo($param) { }

What kind of bugs can PHPStan catch?

PHPStan can catch a wide variety of bugs, from identifying dead code to finding out if you’re using a variable that doesn’t exist. Or if you’re using a variable that is not of the type you’re expecting it to be or unknown method checks. The list goes on.

Installing PHPStan

To install PHPStan, you need to install it as a dev dependency using Composer. You can do so by running the following command.

composer require --dev phpstan/phpstan

Running PHPStan

Once installed, you can run PHPStan by running the PHPStan binary in the vendor/bin directory from your project’s root.

You’ll need to specify at least one directory or file to analyse.

So, if you want to run PHPStan on the src directory, you can do so by running the following command.

vendor/bin/phpstan analyse src

PHPStan has something called Ruleset levels. These are the levels of strictness you want PHPStan to run on. By default, it runs on the 0 level which is the loosest level. The higher the level, the stricter the rules are.

You can change this by passing the --level option.

For instance, if you want to run PHPStan on the strictest level, you can do so by passing the 9 or max level.

vendor/bin/phpstan analyse --level 9
vendor/bin/phpstan analyse --level max

If you’re just getting your feet wet with PHPStan, I would recommend you to start with the 0 level and then gradually increase the level as you get comfortable with it.

Here’s how the output of PHPStan looks like when I ran it on the level 8 on one of my projects.

Running PHPStan

As you can tell, it has found a lot of errors in my code in a nice tabular format. It even shows the file name and the line number where the error is occurring. It also gives you the link to its documentation to tackle some of the errors.

You can solve most of the errors by properly type-hinting the variables and return types. For the rest of the errors, you can write appropriate DocBlocks to solve them.

Using PHPStan with VS Code

If you’re using VS Code, you can install the third-party PHPStan extension which will run PHPStan in the background and show you the errors in the editor itself as you type the code.

The extension will use the configuration from the phpstan.neon file in the root of your project. If it doesn’t find one, it will use the default configuration.

In closing

While IDEs like PHPStorm (or PHP Intelephense in VS Code) can already help you catch errors in your code to some extent, PHPStan can help you catch errors that are not-so-obvious and can be overlooked in a full-blown manner.

It can also help you catch errors in your code even before you write tests for it. And that’s a great thing to have in your arsenal.

Learn the fundamentals of PHP 8 (including 8.1, 8.2, and 8.3), the latest version of PHP, and how to use it today with my new book PHP 8 in a Nutshell. It's a no-fluff and easy-to-digest guide to the latest features and nitty-gritty details of PHP 8. So, if you're looking for a quick and easy way to PHP 8, this is the book for you.

Like this article? Consider leaving a


👋 Hi there! I'm Amit. I write articles about all things web development. You can become a sponsor on my blog to help me continue my writing journey and get your brand in front of thousands of eyes.