PHPStan

The phpstan jobs run static code quality checks using PHPStan

Configuration

Configuration discovery leverages PHPStan's defaults: it will use phpstan.neon when present, fall back to phpstan.neon.dist, and finally phpstan.dist.neon. If none of these exist in the project root, a default configuration is used.

Baseline file

Projects can optionally specify baseline file(s) of messages to ignore. The default baseline file phpstan-baseline.neon stored in the project top-level folder, will be included if using the default phpstan.neon config file. If your project's baseline file is called something different, then specify the name in the _PHPSTAN_BASELINE_FILENAME variable:

variables:
  _PHPSTAN_BASELINE_FILENAME: 'your-baseline-file.neon'

To include multiple baseline files, your project will need its own phpstan.neon config file with a includes: keyword, for example:

includes:
  - phpstan-baseline.neon
  - second-baseline-file.neon

A new baseline file is created which is available as a job artifact for download. This file will contain all warnings found, including those ignored in the single baseline file named in _PHPSTAN_BASELINE_FILENAME. Unmatched messages in the baseline file are reported in the log.

Variants

In addition to testing at the current core version, the phpstan job has optional variants for the previous major, next major and minor core versions and the maximum PHP version.

Consider the PHP version when interpreting the results of the PHPStan job, as the analysis may give different results between major versions of PHP.

Customization

If you do not want this job to be run, set the variable SKIP_PHPSTAN: 1

To add additional arguments to the PHPStan command, you can use the _PHPSTAN_EXTRA variable. This can be set at the global level, or just for a specific variant. For example:

'phpstan (next minor)':
  variables:
    _PHPSTAN_EXTRA: '--debug'

The --debug option shows the name of each file that is being checked.

The pipeline variable _PHPSTAN_LEVEL can be set to a value from 0-9 to specify how relaxed or severe the code quality checks should be. This can be used to temporarily override the value in your phpstan.neon file. If no value is given, either in the variable or the file, then the default of 0 is used. See the PHPStan rule levels for more information.

Object Oriented Hooks in PHPStan (previous major)

Drupal 11 introduces object oriented hooks using the #[Hook] attribute. It also uses the #[LegacyHook] attribute for backwards compatibility. However, when running phpstan (previous major), these will be reported as unknown attributes.

One option is to use @phpstan-ignore-next-line directives to tell PHPStan to skip the attributes. However this is not ideal, as it will suppress any problems PHPStan might find in the attribute for current and future versions as well as previous major.

An alternative approach is to use a before script to remove the attributes lines from the source before running PHPStan. As the container gets thrown away after the checks complete, this will have no impact on any other tests. For example:

phpstan (previous major):
  before_script:
    - sed -i '/#\[LegacyHook\]/d' $DRUPAL_PROJECT_FOLDER/*.module
    - sed -i '/#\[Hook/d' $DRUPAL_PROJECT_FOLDER/src/Hook/*.php