Config Reference

Getting started?

This page is about all the configuration options PHPStan has. If you want to learn how to start using PHPStan, head to Getting Started instead.

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

Config file #

A config file can be passed to the phpstan executable using the -c|--configuration option:

vendor/bin/phpstan analyse -c phpstan.neon

When using a config file, you have to pass the --level|-l option to analyse command (default value 0 does not apply here), or provide it as a level parameter in the config file itself. Learn more about other command line options »

If you do not provide a config file explicitly, PHPStan will look for files named phpstan.neon or phpstan.neon.dist in current directory.

The resolution priority is as such:

If config file is provided as a command line option, it will be used.
Otherwise, if phpstan.neon exists in the current working directory, it will be used.
Otherwise, if phpstan.neon.dist exists in the current working directory, it will be used.
If none of the above is true, no config will be used.

The usual practice is to have phpstan.neon.dist under version control, and allow the user to override certain settings in their environment (on their own computer or on a continuous integration server) by creating phpstan.neon that’s present in .gitignore file. See Multiple files for more details:

Multiple files #

The NEON format supports an includes section to compose the final configuration from multiple files. Let’s say the phpstan.neon.dist project config file looks like this:

parameters:
	level: 6
	paths:
		- src
		- tests

If the user doesn’t have certain PHP extensions, wants to ignore some reported errors from the analysis, and to disable parallel CPU processing, they can create phpstan.neon file with this content:

includes:
	- phpstan.neon.dist

parameters:
	ignoreErrors:
		- '#Function pcntl_open not found\.#'
	parallel:
		maximumNumberOfProcesses: 1

Relative paths in the includes section are resolved based on the directory of the config file is in. So in this example, phpstan.neon.dist and phpstan.neon are next to each other in the same directory.

Ignoring errors #

Learn more about ignoring errors in the user guide.

Related config keys: ignoreErrors, reportUnmatchedIgnoredErrors.

Autoloading #

Learn more about autoloading in the user guide.

Related config keys: autoload_directories, autoload_files.

Bootstrap #

If you need to initialize something in PHP runtime before PHPStan runs (like your own autoloader), you can provide your own bootstrap file:

parameters:
	bootstrap: phpstan-bootstrap.php

Relative path in the bootstrap key is resolved based on the directory of the config file is in.

Caching #

By default, PHPStan stores its cache files in sys_get_temp_dir() . '/phpstan' (usually /tmp/phpstan). You can override this by setting the tmpDir parameter:

parameters:
	tmpDir: tmp

Relative path in the tmpDir key is resolved based on the directory of the config file is in. In this example PHPStan cache will be stored in tmp directory that’s next to the configuration file.

Analysed files #

PHPStan accepts a list of files and directories on the command line:

vendor/bin/phpstan analyse -c src tests

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 you provide analysed paths to PHPStan on the command line and in the config file at the same time, they are not merged. Only the paths on the command line will be used.

You should only analyse files with the code you’ve written yourself. There’s no need to analyse the vendor directory with 3rd party dependencies because it’s not in your power to fix all the mistakes made by the developers you don’t work with directly.

Yes, PHPStan needs to know about all the classes, interfaces, traits, and functions your code uses, but that’s achieved through autoloading, not by including the files in the analysis.

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 excludes_analyse key. Each entry is used as a pattern for the fnmatch() function.

parameters:
	excludes_analyse:
		- tests/*/data/*

By default, PHPStan analyses only files with the .php extension. To include other extensions, use the fileExtensions key:

parameters:
	fileExtensions:
		- php
		- module
		- inc

Rule level #

Learn more about rule levels in the user guide.

Instead of using the CLI option --level, you can save some keystrokes each time you run PHPStan by moving the desired level to the config file:

parameters:
	level: 6

Custom ruleset #

PHPStan requires you to specify a level to run which means it will choose the enforced rules for you. If you don’t want to follow the predefined rule levels and want to create your own ruleset, tell PHPStan to not require a level by setting customRulesetUsed to true:

parameters:
	customRulesetUsed: true

You can then choose your own ruleset by copying parts of the level configuration files from PHPStan sources, or include your own custom rules.

Solving undefined variables #

Learn more about solving undefined variables in Writing PHP Code.

Related config keys: earlyTerminatingMethodCalls, earlyTerminatingFunctionCalls.

Universal object crates #

Classes without predefined structure are common in PHP applications. They are used as universal holders of data - any property can be set and read on them. Notable examples include stdClass, SimpleXMLElement (these are enabled by default), objects with results of database queries etc. Use universalObjectCratesClasses key to let PHPStan know which classes with these characteristics are used in your codebase:

parameters:
	universalObjectCratesClasses:
		- Dibi\Row
		- Ratchet\ConnectionInterface

Constants #

Learn more about letting PHPStan know about your global constants in the user guide.

Sometimes your constants can have different values in different environments, like DATABASE_ENGINE that can have different values like mysql or pgsql. To let PHPStan know that the value of the constant can be different, and prevent errors like Strict comparison using === between 'pgsql' and 'mysql' will always evaluate to false., add the constant name to dynamicConstantNames key:

parameters:
	dynamicConstantNames:
		- DATABASE_ENGINE
		- Foo::BAR_CONSTANT # class constants are also supported

Stub files #

Learn more about stub files in the user guide.

Related config key: stubFiles.

Stricter analysis #

Existing outside of rule levels there are additional parameters affecting analysis result you can tune.

`polluteScopeWithLoopInitialAssignments` #

default: true (strict-rules sets it to false)

example: with true, with false

When set to false it prevents reading variables set in for loop initial statement and while loop condition after the loop.

`polluteScopeWithAlwaysIterableForeach` #

default: true (strict-rules sets it to false)

example: with true, with false

When set to false it prevents reading key and value variables set in foreach when iterating over a non-empty array.

`polluteCatchScopeWithTryAssignments` #

default: false

If you use some variables from a try block in your catch blocks, set this parameter to true.

try {
	$author = $this->getLoggedInUser();
	$post = $this->postRepository->getById($id);
} catch (PostNotFoundException $e) {
	// $author is probably defined here
	throw new ArticleByAuthorCannotBePublished($author);
}