README

Coding standard dependencies for Drupal components.

Installation

Install the code review component via Composer:

composer require --dev openeuropa/code-review-drupal

In your project root create the following grumphp.yml.dist:

imports:
  - { resource: ./vendor/openeuropa/code-review-drupal/dist/drupal-conventions.yml }

Commands

GrumPHP tasks will be run at every commit, if you wish to run them without performing a commit use the following command:

./vendor/bin/grumphp run

If you want to simulate the tasks that will be run when creating a new commit:

./vendor/bin/grumphp git:pre-commit

Check GrumPHP documentation for more.

Customization

This component offers a variety of ready conventions that all projects need to follow. This list of default conventions can be found in CONVENTIONS.md.

Since GrumPHP uses the Symfony Dependency Injection component you can override specific parameters in your project's grumphp.yml.dist file as follows:

imports:
  - { resource: ./vendor/openeuropa/code-review-drupal/dist/drupal-conventions.yml }

parameters:
  tasks.git_commit_message.matchers: ['/^JIRA-\d+: [A-Z].+\./']

Below the list of task parameters can that be overridden on a per-project basis:

• tasks.phpcs.standard
• tasks.phpcs.ignore_patterns
• tasks.phpcs.triggered_by
• tasks.phpcs.whitelist_patterns
• tasks.phpcs.warning_severity
• tasks.phpstan.autoload_file
• tasks.phpstan.configuration
• tasks.phpstan.level
• tasks.phpstan.force_patterns
• tasks.phpstan.triggered_by
• tasks.phpstan_deprecations.blocking
• tasks.git_commit_message.matchers

PHPStan deprecations

Deprecations do not fail the build. PHPStan runs as two GrumPHP tasks:

• phpstan reports every error except deprecations, and fails the run.
• phpstan_deprecations reports only deprecations and is non-blocking: GrumPHP lists them as failed (in yellow), but exits successfully.

An error counts as a deprecation when its message starts with "Deprecated" or contains " deprecated" as a word, such as Call to deprecated method ... from phpstan-deprecation-rules, Not supporting attribute discovery is deprecated in drupal:11.2.0 ... from phpstan-drupal or Deprecated in PHP 8.4: .... Names such as $deprecated, Foo::deprecated() or array{deprecated: bool} do not count. Errors worded differently, even if they come from a deprecation rule, still fail the build.

Both tasks run your project's PHPStan configuration (tasks.phpstan.configuration), so its excludePaths and ignoreErrors apply to both.

Only GrumPHP treats deprecations as warnings: running PHPStan directly with your configuration still reports them as errors.

Keep in mind that:

• When selecting tasks with --tasks or in testsuites, include phpstan_deprecations next to phpstan, or deprecations are not reported.
• Errors PHPStan cannot ignore, such as syntax errors or ignore patterns that are no longer matched, are reported by both tasks.
• If your PHPStan baseline counts deprecations (count:), going over that count fails the phpstan task: PHPStan reports the overflow as an error that cannot be ignored.
• Overriding the whole phpstan task in your grumphp.yml replaces this setup: that task then reports deprecations as errors again. To disable PHPStan, disable both phpstan and phpstan_deprecations.
• With stop_on_failure: true, deprecations are only reported when all other tasks pass, as phpstan_deprecations runs last.

To make deprecations fail the build again, set the tasks.phpstan_deprecations.blocking parameter in your project's grumphp.yml.dist, next to the other parameters:

imports:
  - { resource: ./vendor/openeuropa/code-review-drupal/dist/drupal-conventions.yml }

parameters:
  tasks.phpstan_deprecations.blocking: true

Set it under parameters:, not under grumphp: tasks:: redefining the phpstan_deprecations task there replaces the whole task.

It is also possible to extend the list of tasks to be run by adding tasks under the tasks: tree as shown below:

imports:
  - { resource: ./vendor/openeuropa/code-review-drupal/dist/drupal-conventions.yml }

grumphp:
  tasks:
    phpparser: ~

GrumPHP already has a series of tasks that can be used out of the box, you can find the complete list in the GrumPHP tasks page.

If you wih you can create your own tasks as explained in the GrumPHP extensions page.

Transition from code-review 2.x

If you wish to transition to code-review-drupal from code-review version 2.x, please replace the package via Composer:

composer remove --dev openeuropa/code-review
composer require --dev openeuropa/code-review-drupal

Besides replacement of the package, some adjustments are needed in grumphp.yml file.

This component removes ExtraTasks extension. Any aditional task previously declared in extra_tasks will need to be placed inside tasks under grumphp tree.

- extra_tasks:
-   phpparser:
-      ignore_patterns:
-       - vendor/
-
- grumphp:
-   extensions:
-     - OpenEuropa\CodeReview\ExtraTasksExtension

+ grumphp:
+   tasks:
+     phpparser:
+      ignore_patterns:
+        - vendor/

In addition, PHP Mess Detector is no longer available as part of the configured tasks. The task and related parameters have been removed. If you wish to continue using PHP Mess Detector, you can add it as part of GrumPHP as previously described.

All other conventions and parameters remain the same.