axelerant / drupal-quality-checker

Pre-commit code quality checker for Drupal based projects.

Package for Drupal Code Quality presets

This has been customised from vijaycs85/drupal-quality-checker for Axelerant needs. Apart from a different template file, it uses the Axelerant logo.

Installation

Upgrading from Beta 8? Read the instructions for changes you need to make to grumphp.yml.dist.

composer require --dev axelerant/drupal-quality-checker

This will add the plugin to your project and copy the default configuration files. These files are:

• grumphp.yml.dist
• phpcs.xml.dist
• phpmd.xml.dist
• phpstan.neon.dist

Since these are .dist files, the plugin will overwrite them on every composer install. If you mean to customize the default settings, then we recommend that you rename them to remove the .dist suffix. As such, it is a good idea to add these .dist files to your .gitignore file.

Usage

No additional steps required, but if git hooks aren't fired, run php ./vendor/bin/grumphp git:init. For additional commands, look at grumhp's documentation.

Customising

Almost all customising begins with first copying the grumphp.yml.dist file to your project. Make sure you have the file.

Adding tasks

There are various tasks you can add and customise in your grumphp.yml. Read the online documentation for GrumPHP tasks to see the tasks you can use and configure.

Forcing commit message format

To configure commit message structure, use the git_commit_message task. For example, to enforce the commit message contains the Jira issue ID, use the rule as the following snippet. More options are documented online.

# grumphp.yml
grumphp:
  tasks:
    git_commit_message:
      matchers:
        Must contain issue number: /JIRA-\d+/

Disable commit banners

GrumPHP supports banners to celebrate (or scold) on your commit. This is fun but it is possible it gets on your nerves. If you don’t want it, edit the grumphp.yml file and replace the following parameters:

# grumphp.yml
grumphp:
    ascii: ~

You could even disable specific ones like this:

# grumphp.yml
grumphp:
    ascii:
        succeeded: ~

Overwrite phpmd ruleset

Copy the ruleset to the project root first

cp vendor/axelerant/drupal-quality-checker/phpmd.xml.dist phpmd.xml

Edit it as per your needs and commit. Remember to modify the grumphp.yml file with the new path.

# grumphp.yml
grumphp:
  tasks:
    phpmd:
      ruleset: ['phpmd.xml']

Customise phpcs rules

Copy the ruleset to the project root first

cp vendor/axelerant/drupal-quality-checker/phpcs.xml.dist phpcs.xml

Edit it as per your needs and commit. Remember to modify the grumphp.yml file with the new path.

# grumphp.yml
grumphp:
  tasks:
    phpcs:
      standard: ['phpcs.xml']

Customise phpstan rules

Copy the ruleset to the project root first

cp vendor/axelerant/drupal-quality-checker/phpstan.neon.dist phpstan.neon

Edit it as per your needs and commit. Remember to modify the grumphp.yml file with the new path.

# grumphp.yml
grumphp:
  tasks:
    phpstan:
      configuration: phpstan.neon

More about scaffolding

As described before, this package uses drupal/core-composer-scaffold plugin to scaffold a few files to the project root. This is not required but there is a good chance you are already using it if you're building a Drupal site.

The scaffolding operation runs with every composer operation and overwrites files. Only the file grumphp.yml.dist is not overwritten during subsequent operations. If you are customising any of the other configuration files and don't want the updates to overwrite your changes, you can override the behaviour in your composer.json file. For example, to skip phpmd.xml.dist from being overwritten, add this to your composer.json:

  "name": "my/project",
  ...
  "extra": {
    "drupal-scaffold": {
      "file-mapping": {
        "[project-root]/phpmd.xml.dist": false
      }
    }
  }

For more details, read the "Excluding Scaffold files" section of the documentation for the core-composer-scaffold plugin.

Upgrading from Beta 8

GrumPHP 0.19 introduced a breaking change to the structure of the YAML file. The template in this repository is updated as per the new structure. However, you would need to change the YML files on your projects before you update to Beta 9 or later.

Fortunately, the change is simple and in many cases would only require a one line change. Rename the parameters section to grumphp. Our default template contains two parameters which still need to remain under parameters. They are git_dir and bin_dir. Look at the diff of the change to understand what needs to be changed in your grumphp.yml file. Also, read more at the release page for GrumPHP 0.19.

Lastly, you can watch this video where I upgrade this on a project. Link: https://youtu.be/XoFJfBcZF58

drupal-quality-checker's Issues

Consider using Phive to bring in dependencies

Some of the tools we use require conflicting dependencies which makes it difficult to use the latest or even supported versions of these tools. For example, the latest release of PHPCPD is version 6 but only PHPCPD 4 may be installed on a Drupal 8 site (because of Symfony dependencies). This is even more of a problem because GrumPHP has broken support for PHPCPD 4. This means that the version of PHPCPD that gets installed for Drupal 8 does not work at all. We can't change the constraints or this entire package will stop working for Drupal 8. The only options are to ignore the error or remove the dependency on PHPCPD.

Phive lets us avoid all of these problems by installing the PHAR versions of the tools rather than through composer. This keeps the project free of these dependencies. The problem is that this requires users to install another tool (Phive) and also an extra step to run phive install after installing dependencies through composer.

Cannot use root namespace classes/interfaces/traits

Coder recently added a sniff to check if root namespace classes (or interfaces or traits) are fully namespaced. As a consequence, the following code does not pass the sniff.

use Twig_Extension;
use Twig_SimpleFilter;

new Twig_Extension();

The new sniffs check that the code references classes in the root namespace use the full name and not get imported.

new \Twig_Extension();

However, this causes an issue with phpmd: the above example will not pass phpmd's cleancode rules.

There is no workaround to this situation except bypassing checks (git commit -n).

We should adhere to Drupal's coding standards, or at least, coder's interpretation of Drupal's coding standards in this case. The fix would be to exclude this specific rule from phpmd.

PHP Warning: preg_match(): Unknown modifier 't'

I have noticed that when paths in ignore_patterns have a / at the end, it generates the following warning while running GrumPHP:

PHP Warning: preg_match(): Unknown modifier 't' in phar:///var/www/html/vendor/phpro/grumphp-shim/grumphp.phar/vendor/symfony/finder/Iterator/MultiplePcreFilterIterator.php on line 53

Solutions:
Fix paths for ignore_patterns in grumphp.yml.dist

Exclude "\Drupal\Core\Site\Settings class of PHPMD StaticAccess rule

Hello,

It is not possible to instantiate or use dependency injection to retrieve a site settings.
So it is a good idea to add an exclusion for this class in the phpmd.xml.dist file

Copy configuration files to the project root

It turns out that there are various issues with using drupal/core-composer-scaffold to copy the files. The most obvious one is that someone has to remember to add this package to composer.json extra section. It's documented, but it's not typical and people are likely to forget.

Another problem is that GrumPHP generates a configuration file on installation as well and there is no clear way to disable this. Fortunately, it checks if a configuration file is already present before generating one. So, if we generate our configuration file before, GrumPHP won't create one. However, the drupal/core-composer-scaffold plugin copies files at the very end which means we can't create the file before.

We should figure out a way to copy the file before events in GrumPHP are fired. The current solution in my mind is to write our own composer plugin which executes before GrumPHP and copies the files. The benefit with this approach is that we no longer have to rely on drupal/core-composer-scaffold to copy files either. So, it's a win-win except that we now have to maintain a plugin just for this.

grumpy.txt & happy.txt should be different

The default files are the same which is confusing when using a non color term.

Not working with Drupal 10

Problem Statement:

I'm not able to use it on Drupal 10 project. The problem is coming because of friendsoftwig/twigcs
https://github.com/axelerant/drupal-quality-checker/blob/v1.2.0/composer.json#L16

Possible Solution:

Update the dependencies from:
"friendsoftwig/twigcs": "^3.2 || ^4.0 || ^5.0",
to
"friendsoftwig/twigcs": "^3.2 || ^4.0 || ^5.0 || ^ 6.0",

Exclude "\Drupal\Core\Render\Element\Checkboxes" class of PHPMD StaticAccess rule

Hi,

It is not possible to instantiate or use dependency injection to use Checkboxes methods (e.g. Checkboxes::detectEmptyCheckboxes())
So it is a good idea to add an exclusion for this class in the phpmd.xml.dist file

Remove phpcpd as it does not recommend composer based installation

Using composer for development tools have problems with conflicting dependencies (#12) and phpcpd makes it clear that they don't recommend composer. More here: https://twitter.com/s_bergmann/status/999635212723212288 and sebastianbergmann/phpcpd@dac917d.

Update to the 1.0 release of GrumPHP

There is a 1.0 release of GrumPHP. We should determine if we need to change our config file and then update to the new version.

One issue I noticed so far is that GrumPHP is now prompting for creating a config on installation. We should find an option to disable that.

Review relevant tasks for addition

Look at all supported GrumPHP tasks and adopt those that make sense. https://github.com/phpro/grumphp/blob/v2.x/doc/tasks.md

Should we overwrite config files and .dist files?

After the discussion here, I am reconsidering the decision to only output .dist files and overwrite them with every install. Does it feel very confusing and potentially fragile? What do you think of writing non-dist files and then having users own them. We could build tooling to let users diff and update their config once we roll out updates (it's tricky to do that but we can discuss this later).

Use PHPCompatibility develop version for PHP 8+ check

Hi,
Maybe I'm missing something but PHPCompatibility last release (9.3.5) is three years old and doesn't handle properly PHP 8.0 or 8.1 compatibility:

• PHPCompatibility/PHPCompatibility#809
• PHPCompatibility/PHPCompatibility#1299

I think drupal-quality-checker should use 'dev-develop' or '*' in order to be able to be use this standard properly with modern PHP versions.

Update static calls exceptions list

Update static calls exceptions list.

Add TwigCS

GrumPHP supports TwigCS, so we don't have to do much. We should just put it in our default template.

Move all task dependencies to suggestions

We require the following dependencies:

        "dealerdirect/phpcodesniffer-composer-installer": "*",
        "drupal/coder": "^8.3.7",
        "friendsoftwig/twigcs": "^4.0 || ^5.0 || ^6.0",
        "php-parallel-lint/php-parallel-lint": "^1.2",
        "phpcompatibility/php-compatibility": "^9.0",
        "phpmd/phpmd": "^2.8",
        "sebastian/phpcpd": "^3.0 || ^4.0 || ^5.0 || ^6.0"

There is always a possibility that these dependencies could introduce conflicts in some projects. Consider moving them to composer.json suggested rather than require so that the dependencies are not locked.

The problem is if we remove all the dependencies, then our default grumphp config will fail. We will need to make it clear in the documentation that the user is responsible for installing the relevant packages.

Upgrade to grumphp v2

As per the changelog, there is no change in usage of GrumPHP. However, the task extension system has changed but this does not affect this repository.