QA of Drupal 9 / 10 website

Since I work with Drupal, I had a lot of project, with some case of third party application maintenance.
One of the most consistent problem is the very low quality of the code, whatever it's a big company or a small client, there is always a lack of technical management.

Drupal the culprit?

Drupal is very flexible and is probably providing the most powerful site building in the industry. But flexibility gives you more way to do the same task, in a bad way. This bad way can objectively be quantified and lead to more difficulty in reading the code, understanding the site building method, maintain and evolve the project.

Main surprise in Drupal 6/7 was the usage of a lot of PHP in the templates, with all the logic and business rules. At the time Drupal used pure PHP Template engine for theming. A lot of developers with few knowledge of Drupal would put all the code in the templates. which lead to a lot of problems, readability, bug fixes, disconnection from back office, hard to maintain...

Twig to save them all

With Drupal 8, one of the major change was the usage of Twig as templating engine, so now no more PHP in templates! But bad practices can outlive any good one!
You can still use PHP in your theme inside the specific .theme file. It's meant to contain a minimal set of PHP code, as hook_theme_suggestions_HOOK_alter() to have more flexibility in templates overriding and some hook_preprocess() to add or alter lightly some variables when you cannot do it with a field formatter, which is pretty rare.
But unfortunately this open door give the opportunity for non Drupal developers to put all the code in an insanely unreadable manner in this file.

For medium/big companies, to not use any quality insurance tool is a technical lead problem. Sometimes a money concern, even if it's a bad calculation.
But for small companies, to have a technical lead or director is most often not possible. Luckily we have today a lot of Open source quality insurance tools, easy to use, that give the opportunity to simply evaluate the quality of what is produced.
There is some very good paid tools on the market, but this is not the subject of this article.

QA tools for PHP in Drupal

Here is my selection I'm using to quickly evaluate the quality of a project.

Off course PHP Code Sniffer to check if the code comply to Drupal coding standards. It's not enough to evaluate the quality of the code but it's a good start. When respecting standards, it help make the code more easy to understand for any new developer.
And it give a quick clue about the rigor of the developer writing the code.

PHPMD - PHP Mess Detector is a very good tool to have a quick overview about the quality of the PHP code.

PHP Copy/Paste Detector will detect part of code that are the same over the project, created by talented Sebastian Bergmann, who is behind PHPunit.

From the same author, PhpLoc, a tool for quickly measuring the size and analyzing the structure of a PHP project.

PhpMetrics in the same area as PHPLoc, with more design, to evaluate size, structure, quality and problems inside a project.

And for this article PHP Stan is a static analysis tool, meant to detect problems in the code without running it. There is a side project for Drupal configuration, which make this tool essential on all Drupal projects.

There is more tools around, but this is just my selection for Drupal.

Quick install of tools for Drupal 8/9

There is a project that will help us to run all these tools together in one go, the very good phpqa. Here is a quick instruction to setup and run.
From the root of the project, install it with composer:

composer require edgedesign/phpqa drupal/coder dealerdirect/phpcodesniffer-composer-installer --dev

Then you need a minimum set of configuration files to put at the root of the project:

A file .phpqa.yml

  # Default common config for Phpqa.
  # @see https://github.com/EdgedesignCZ/phpqa/blob/master/.phpqa.yml
  phpcs:
    standard:
      - Drupal
      # Drupal best practices, uncomment for perfect standard checking.
      # - DrupalPractice
    ignoreWarnings: true
    reports:
      cli:
        - full
      file:
        checkstyle: checkstyle.xml
  phpmd:
    standard: .phpmd.xml
  phpcpd:
    minLines: 5
    minTokens: 70
  phpqa:
    ignoredDirs: "vendor,bootstrap,tests"
    ignoredFiles: "Readme.md,*Test.php"
    report: true
    verbose: true
    execution: parallel
    extensions:
      - php
      - inc
      - module
      - install
      - test
      - profile
      - theme
  

A file .phpmd.xml to get from my Gitlab project.

Run and understand results

Simply run it from the root of the project. Command here will use specific tools with a goal of no standards errors or repetition of code:

vendor/bin/phpqa --tools=phpcs:0,phpcpd:0,phpmd,phploc,phpmetrics --analyzedDirs=./web/modules/custom,./web/themes/custom --buildDir ./build

A folder ./build is created with the result.

You can then navigate in the results starting with phpqa.html file. The number of errors will give you a good estimate of the quality of the project.

For phpcs, it's possible to reach a no error goal. A code respecting standards is not more complex. Same for phpcpd, it's not normal to have the same portion of code in multiple places. It's one of the principle of programing, don't repeat yourself!
For phpmd it's more subtle, you need to check the nature of errors.
Phploc and phpmetrics will give a more global overview of the quality.

PHPStan specific usage

For now there is a PR in progress to use PHPstan in phpqa, so we are using it as a standalone. First step is to install it:

composer require mglaman/phpstan-drupal phpstan/phpstan-deprecation-rules phpstan/extension-installer --dev

Here is the specific configuration file to put at the root of the project with name phpstan.neon :

parameters:
level: 1
excludePaths:
  analyseAndScan:
    - */tests/*
    - */Tests/*
inferPrivatePropertyTypeFromConstructor: true
checkMissingIterableValueType: false
## Ignore some errors.
reportUnmatchedIgnoredErrors: false
ignoreErrors:
  - '#Unsafe usage of new static\(\).#'

Level 1 is pretty low, PHPStan is from 0 to 9. But Drupal is not yet passing a high level and this is a good starting point to evaluate the quality. A level 3 would be a very good goal for any custom code.

Launch analysis with PHPStan:

vendor/bin/phpstan analyse web/modules/custom/ web/themes/custom/

Deprecated code

In the lifecycle of a project, it can be useful to detect deprecated code early, to ease any upgrade. PhpStan will help to do that with specific rules to install:

composer require phpstan/phpstan-deprecation-rules --dev

When launching again the analysis, this time deprecated code detection will be included.

Conclusion

This first step will give you an objective way to quantify the quality of a project. It's just an indication, it will not rate the site building used on Drupal, but it's still a very good start.

A second step is to integrate these tools directly in a continuous integration process. This will help to maintain quality over the lifecycle of the project.

You can have an example of this integration with my project Gitlab ci for Drupal.