Perform static analysis of Drupal PHP code with PHPStan and PHPStan-Drupal on Drupal using PHP 8.

For example:

# Run Scans drupal 11 support
docker run --rm \
  -v $(pwd)/example01/modules_i_want_to_test:/var/www/html/modules/custom \
  dcycle/phpstan-drupal:5 /var/www/html/modules/custom

# Run Scans drupal 9 support
docker run --rm \
  -v $(pwd)/example01/modules_i_want_to_test:/var/www/html/modules/custom \
  dcycle/phpstan-drupal:4 /var/www/html/modules/custom
docker run --rm \
  -v $(pwd)/example02/modules_i_want_to_test:/var/www/html/modules/custom \
  dcycle/phpstan-drupal:4 /var/www/html/modules/custom
docker run --rm \
  -v $(pwd)/example03/modules_i_want_to_test:/var/www/html/modules/custom \
  -v $(pwd)/example03/phpstan-drupal:/phpstan-drupal \
  dcycle/phpstan-drupal:4 /var/www/html/modules/custom
docker run --rm \
  -v $(pwd)/example04/some_module:/var/www/html/modules/custom/some_module \
  -v $(pwd)/example04/phpstan-drupal:/phpstan-drupal \
  dcycle/phpstan-drupal:4 /var/www/html/modules/custom

Ignoring a single line of code

PHPStan by itself supports ignoring an error on a single line, like this:

// @phpstan-ignore-next-line
...some offending code...;

or even:

// Whatever whatever @phpstan-ignore-next-line whatever whatever.
...some offending code...;

Obviously, we generally want to fix the underlying problem, but if for whatever reason you need to ignore an error, you can now do so.

Version history and migrating from one version to another

• dcycle/phpstan-drupal:5 is based on Drupal 11, and PHP 8
• dcycle/phpstan-drupal:4 is based on Drupal 9, and PHP 8; Drupal 8-specific code will trigger errors; the deprecated autoload_files has been replaced with bootstrapFiles in docker-resources/phpstan.neon. Version 4 now also includes functionalty from dcycle/docker-drupal-check.
• dcycle/phpstan-drupal:3 is based on Drupal 9; Drupal 8-specific code might trigger errors.
• dcycle/phpstan-drupal:2 uses @phpstan-ignore-next-line to ignore the next line of code.
• dcycle/phpstan-drupal:1 uses phpstan:ignoreError to ignore the next line of code.

Bootstrap files and mock versions of code

If you get an error like class Drupal\some_module\Plugin\Widget not found, you might need to define a mock version of that class. This might be the case if your code depends on contrib code, for example. Here is how to do it:

• Start by creating a custom config file (see below)

• In your custom config file, define these lines:

  parameter: ... bootstrapFiles: - /phpstan-drupal/mock-classes.php

• Then create a file called ./tests/lib/phpstan/mock-classes.php, with

Custom config file

If you need a custom config file, for example if you want a different level, or to tell PHPStan to ignore certain files, you can do so by including the provided config file. See example05 for details; it can be run using:

docker run --rm \
  -v $(pwd)/example05/modules_i_want_to_test:/var/www/html/modules/custom \
  dcycle/phpstan-drupal:4 /var/www/html/modules/custom \
  -c /var/www/html/modules/custom/phpstan.neon

If you look at the custom config file in example05, it looks like this:

# See https://github.com/dcycle/docker-phpstan-drupal/blob/master/README.md#custom-config-file
parameters:
  excludePaths:
    - */tests/*
includes:
  - /var/www/html/phpstan.neon

This tells PHPStan that we want our custom configuration exclude paths like */tests/* from PHPStan analysis, and use the default /var/www/html/phpstan.neon for everything else. /var/www/html/phpstan.neon is not in your own code, it is in the dcycle/phpstan-drupal container. Its contents can be found here.

Deprecation testing

In the ./docker-resources/composer.json file you will find the following requirement as per the PHPStan-Drpual documentation:

phpstan/phpstan-deprecation-rules

In the ./docker-resources/phpstan.neon file you will find the following include, again as per the documentaiton:

vendor/phpstan/phpstan-deprecation-rules/rules.neon

This means that when you have deprecated code in your codebase, it will be detected.

Troubleshooting

Out of memory errors can be fixed by adding --memory-limit=-1 to the end of your call, for example:

docker run --rm \
  -v $(pwd)/example01/modules_i_want_to_test:/var/www/html/modules/custom \
  dcycle/phpstan-drupal:4 /var/www/html/modules/custom \
  --memory-limit=-1

Speed increase if using the M1 chip

• See Docker PHP on the M1 chip, example with Static Analysis on Drupal: 9 times faster, Dcycle Blog, November 17, 2021.

Resources

• This project on GitHub
• This project on Docker Hub