In a phpstan.neon file, what do level, paths, excludePaths and includes do, and how do command-line arguments interact with them?

## The file and how PHPStan finds it PHPStan's configuration is written in **NEON**, a format very close to YAML (tab or space indentation, `-` for list items). Almost everything lives under a `parameters:` key. When you do not pass `-c`, PHPStan looks in the current directory in this order: 1. the file given with `-c` / `--configuration`; 2. `phpstan.neon`; 3. `phpstan.neon.dist`; 4. `phpstan.dist.neon`; 5. otherwise, no config at all. The usual convention is to commit `phpstan.neon.dist` (or `phpstan.dist.neon`) and let each developer or CI machine create a git-ignored `phpstan.neon` that includes it and overrides a few settings. ## The four keys | Key | What it does | Notes | |---|---|---| | `level` | the rule level, 0 to 10 or `max` | `--level` on the CLI takes precedence | | `paths` | files and directories to analyse | paths on the CLI replace this list, they are not merged | | `excludePaths` | `fnmatch()` patterns to leave out | plain list = `analyseAndScan`; `analyse:` keeps symbols visible | | `includes` | other config files to merge in (top-level key, not under `parameters`) | relative paths resolve against the including file's directory | Relative paths in `paths`, `excludePaths`, `includes` and `tmpDir` are resolved against the **directory of the config file**, not the directory you run the command from. Paths passed on the command line resolve against the current working directory. ## excludePaths in detail - A flat list is shorthand for `excludePaths: analyseAndScan:`: the files are neither analysed nor read for symbols. Use it for files that are broken on purpose, such as test fixtures with invalid PHP. - `excludePaths: analyse:` stops PHPStan reporting errors in those files but still lets it **discover the classes and functions they declare**. That is the right choice for a bundled `src/thirdparty` directory your code calls into. - In PHPStan 2 each entry must be an existing path or a valid `fnmatch` pattern; appending `(?)` marks an entry that may not exist. The old `excludes_analyse` key from 1.x was removed. - Do not put `vendor/` in `paths` to begin with. PHPStan discovers Composer dependencies' symbols automatically; analysing them only reports bugs you cannot fix. ## includes in detail `includes` merges other NEON (or PHP-returned) config files into the current one. Common uses: - A **local override**: `phpstan.neon` with `includes: - phpstan.neon.dist` plus, say, `parallel: maximumNumberOfProcesses: 1` on a small laptop. - **Bleeding Edge**: `includes: - phar://phpstan.phar/conf/bleedingEdge.neon`. - **Extensions** without the extension installer: `includes: - vendor/phpstan/phpstan-strict-rules/rules.neon`. - A generated **baseline** file, which is its own topic. If the same file ends up included twice, for example once by hand and once by `phpstan/extension-installer`, PHPStan refuses to start with a *files are included multiple times* error and suggests removing the manual include. ## How the command line interacts 1. `vendor/bin/phpstan analyse --level 7` runs level 7 whatever the config says. 2. `vendor/bin/phpstan analyse src/Billing` analyses only `src/Billing`, ignoring the config's `paths` list entirely. 3. With a config file present, one of `--level` or `level:` is mandatory; the default level 0 only applies when there is no config. 4. Running with different path lists from run to run also defeats the result cache, which is keyed on the analysed paths. ## Other keys you meet early A few more `parameters` keys come up in almost every real configuration: - `fileExtensions`: PHPStan analyses only `.php` files by default; legacy code with `.inc` or `.module` files needs them listed. - `scanFiles` and `scanDirectories`: code PHPStan should read for symbols but not analyse, such as classes outside Composer's autoloader. - `bootstrapFiles`: PHP files PHPStan **executes** before analysis, for example to register a custom autoloader or define class aliases. - `customRulesetUsed: true`: tells PHPStan not to require a level because you assemble your own rules from the level config files. - `parallel`: tuning for the worker processes, such as `maximumNumberOfProcesses`. ## A complete example ```yaml includes: - phar://phpstan.phar/conf/bleedingEdge.neon parameters: level: 6 paths: - src - tests excludePaths: analyse: - src/Legacy/ThirdParty analyseAndScan: - tests/*/Fixtures/* tmpDir: var/phpstan ``` With this file committed as `phpstan.dist.neon`, `vendor/bin/phpstan` with no arguments analyses `src` and `tests` at level 6 with Bleeding Edge, and keeps its cache in `var/phpstan`.