PHPStan - PHP Static Analysis Tool
PHPStan focuses on finding errors in your code without actually running it. It catches whole classes of bugs even before you write tests for the code. It moves PHP closer to compiled languages in the sense that the correctness of each line of the code can be checked before you run the actual line.
PHPStan requires PHP >= 7.2. You have to run it in environment with PHP 7.x but the actual code does not have to use PHP 7.x features. (Code written for PHP 5.6 and earlier can run on 7.x mostly unmodified.)
PHPStan works best with modern object-oriented code. The more strongly-typed your code is, the more information you give PHPStan to work with.
Installation
To start performing analysis on your code, require PHPStan in Composer:
composer require --dev phpstan/phpstan
Composer will install PHPStan’s executable in its bin-dir which defaults to vendor/bin.
First run
To let PHPStan analyse your codebase, you have to use the analyse command and point it to the right directories.
So, for example if you have your classes in directories src and tests, you can run PHPStan like this:
vendor/bin/phpstan analyse --level [0-9] src tests
Rule Levels
If you want to use PHPStan but your codebase isn’t up to speed with strong typing and PHPStan’s strict checks, you can currently choose from 10 levels (0 is the loosest and 9 is the strictest) by passing -l|--level to the analyse command.
vendor/bin/phpstan analyse -l 6 src tests
The default level is 0. Once you specify a configuration file, you also have to specify the level to run.
Here’s a brief overview of what’s checked on each level. Levels are cumulative - for example running level 5 also gives you all the checks from levels 0-4.
0.basic checks, unknown classes, unknown functions, unknown methods called on $this, wrong number of arguments passed to those methods and functions, always undefined variables.
1.possibly undefined variables, unknown magic methods and properties on classes with __call and __get.
2.unknown methods checked on all expressions (not just $this), validating PHPDocs.
3.return types, types assigned to properties.
4.basic dead code checking - always false instanceof and other type checks, dead else branches, unreachable code after return; etc.
5.checking types of arguments passed to methods and functions.
6.report missing typehints.
7.report partially wrong union types - if you call a method that only exists on some types in a union type, level 7 starts to report that; other possibly incorrect situations.
8.report calling methods and accessing properties on nullable types.
9.be strict about the mixed type - the only allowed operation you can do with it is to pass it to another mixed.
Command Line Usage
PHPStan’s executable file is installed in Composer’s bin-dir which defaults to vendor/bin.
Analysing code
To analyse your code, run the analyse command. Exit code 0 means there are no errors.
vendor/bin/phpstan analyse [options] [<paths>...]
As <paths> you can pass one or multiple paths to PHP files or directories separated by spaces.
To find the options here.
Config Reference
NEON format
PHPStan uses configuration format called NEON. It’s very similar to YAML so if you’re familiar with it, you can also write NEON.
This is how a possible example of a config file can look like:
parameters:
level: 6
paths:
- src
- tests
- file.php
Config file
A config file can be passed to the phpstan executable using the -c|--configuration option:
vendor/bin/phpstan analyse -c phpstan.neon
If you do not provide a config file explicitly, PHPStan will look for files named phpstan.neon, phpstan.neon.dist, or phpstan.dist.neon in the current directory.
Analysed files
You can save some keystrokes each time you run PHPStan by moving the analysed paths to the config file:
parameters:
paths:
- src
- tests
Relative paths in the paths key are resolved based on the directory of the config file is in.
If your codebase contains some files that are broken on purpose (e. g. to test behaviour of your application on files with invalid PHP code), you can exclude them using the excludePaths key.
parameters:
excludePaths:
- tests/*/data/*
This is a shortcut for:
parameters:
excludePaths:
analyseAndScan:
- tests/*/data/*
If your project’s directory structure mixes your own code and third party code (which you’re using for discovering symbols, but don’t want to analyse), the file structure might look like this:
├── phpstan.neon
└── src
├── foo.php
├── ...
└── thirdparty
└── bar.php
In this case, you want to analyse the whole src directory, but want to exclude src/thirdparty from analysing. This is how to configure PHPStan:
parameters:
excludePaths:
analyse:
- src/thirdparty
Additionally, there might be a src/broken directory which contains files that you don’t want to analyse nor use for discovering symbols. You can modify the configuration to achieve that effect:
parameters:
excludePaths:
analyse:
- src/thirdparty
analyseAndScan:
- src/broken
By default, PHPStan analyses only files with the .php extension. To include other extensions, use the fileExtensions key:
parameters:
fileExtensions:
- php
- module
- inc
Top comments (2)
If you're writing enough code without running it to need this tool...i think you're doing something wrong.
If you're writing PHP...run the damn page? you'll know if there's a bug right away lol
Tools such as PHPCS, PSAML and PHPSTAN are used more for applying PSRs than detecting and correcting errors.