Decision Use PHPStan for PHP code static analysis at level 6

accepted

Static analysis catches type errors, logic bugs, and unsafe code paths without running the application, improving code quality at low cost.

Decision

Use PHPStan for static analysis of PHP code on all projects. Integrate it into CI and pre-commit hooks so violations on new code are caught before merge.

All new code we write must be PHPStan level 6 compliant. Existing code in inherited or legacy codebases does not need to be fixed up-front.

Configuration

Add a phpstan.neon file at the project root:

# Configuration file for PHPStan static code checking, see https://phpstan.org .
includes:
  - phar://phpstan.phar/conf/bleedingEdge.neon
  - phpstan-baseline.neon

parameters:

  level: 6

  treatPhpDocTypesAsCertain: false

  ignoreErrors:
    # new static() is a best practice in Drupal, so we cannot fix that.
    - "#^Unsafe usage of new static#"
    - identifier: missingType.iterableValue

Baseline for existing codebases

Projects with a large existing codebase can use PHPStan's baseline feature to ignore all pre-existing violations and enforce level 6 only on new code going forward:

vendor/bin/phpstan analyse --generate-baseline

This generates a phpstan-baseline.neon file that silences known violations. New and modified code will still be checked at level 6. The baseline file should be committed to the repository and gradually reduced over time as legacy violations are fixed.

Consequences

Static analysis will catch type errors, incorrect method calls, and other classes of bugs before code reaches review or production.