You are introducing PHPStan into a 300,000-line legacy PHP codebase; how do you choose the starting level and configure the first runs?

## Goal of the first week On a 300,000-line codebase that has never been analysed, the first PHPStan run at a high level produces tens of thousands of errors, most of them noise. The goal of the first week is not to fix code; it is to get a **configuration whose errors are real** and a **green gate at some level** in CI. ## Step 1: analyse only your own code at level 0 ```bash vendor/bin/phpstan analyse --level 0 --memory-limit 2G src app ``` - **Level 0** checks unknown classes and functions, unknown methods on `$this`, wrong argument counts and always-undefined variables. On old code these reveal both real bugs and gaps in PHPStan's view of the project. - Analyse **only your code**. PHPStan discovers Composer dependencies' symbols automatically; `vendor` does not belong in `paths`. - Large codebases can exceed PHP's `memory_limit`; `--memory-limit` takes a php.ini-style value such as `2G`. PHPStan also runs in parallel child processes by default, tunable under `parameters.parallel`. ## Step 2: turn configuration noise into zero Most first-run errors on legacy code are about **discovery**, not correctness: | Symptom | Likely cause | Fix | |---|---|---| | unknown classes that clearly exist | custom autoloader or `require`-based loading | `scanDirectories` / `scanFiles`, or register the autoloader via `bootstrapFiles` | | unknown class aliases | `class_alias()` at runtime | define them in a `bootstrapFiles` file, which PHPStan executes | | undefined methods on framework objects | `__call`/`__get` magic | install the framework's PHPStan extension | | parse errors in fixtures | files broken on purpose | `excludePaths` | | errors in bundled third-party code | vendored libraries inside `src` | `excludePaths: analyse:` so symbols stay visible | Two further settings pay off early: - `tmpDir` inside the workspace, so the **result cache** can be kept between CI runs and incremental runs take seconds. - `phpVersion` if the analysing machine runs a different PHP version than production. ## Step 3: gate CI at the level you reached As soon as level 0 reports zero, commit `phpstan.dist.neon` with `level: 0` and `paths`, and make CI fail on any error. From that moment no new unknown class or wrong argument count can be merged, which is already worth the effort. ## Step 4: raise one level at a time The levels are cumulative, so each step adds a small family of checks: 1. **1 to 4**: possibly undefined variables, unknown methods on any expression, PHPDoc validation, return and property types, dead code. These are usually real bugs and cheap to fix. 2. **5**: argument types. Expect a noticeable batch of genuine type errors. 3. **6**: missing typehints. On untyped legacy code this is the wall, often thousands of errors that are pure work rather than bugs. 4. **7 and 8**: union types and nullable access, where many production null-pointer bugs are found. 5. **9 and 10**: `mixed`, which only makes sense once most code is typed. At each step: run the next level, estimate the error count, fix or plan, merge, and bump `level` in the config. ## Where baselines and other tools fit - A **baseline** (a sibling topic) records current errors so a higher level applies to new code immediately. The PHPStan docs say it works best for dozens to hundreds of errors and is not the right tool for 15,000; spend that effort on configuration or stay at a lower level. - **Bleeding Edge** and **phpstan-strict-rules** come later, once the target level is green. - Pin the PHPStan version in `composer.json` and upgrade deliberately, so a release with new checks does not break the gate unexpectedly. The answer interviewers want is the order: trustworthy configuration first, a green gate early, then level-by-level progress with the level 6 cost planned rather than discovered.