Skip to content

Mago for Drupal

A Mago extension that adds Drupal's coding standards to the Mago linter and teaches the Mago analyzer about Drupal's services, entities, config and plugins. Together with Mago's own formatter, rules and analyzer, it replaces phpcs, Coder, PHPStan and phpstan-drupal in a Drupal project.

  • Linter rules check the parts of the standards that can't be checked by Mago's own rules. They port the checks of Coder's Drupal and DrupalPractice standards that need to know about Drupal, add a few asked for only in the written standards, and port a few checks of phpstan-drupal. See Linter rules.
  • Analyzer plugins give mago analyze the types of Drupal's services, entities, config and plugins, and port phpstan-drupal's Drupal-specific checks. See Analyzer.
  • Fixes work the way phpcbf fixes Coder's sniffs. Many rules have one, and mago lint --fix applies them. See Fixes.
  • A map from Coder lists every check of Coder's two standards and what takes its place. Search it for the code from a phpcs report or a phpcs:ignore comment. See Coming from Coder. The extension can also read the phpcs:ignore comments themselves, see phpcs ignores.
  • A map from PHPStan lists every rule and extension of phpstan-drupal and what takes its place, how a phpstan.neon moves to Mago, and which issue codes go with each PHPStan level. See Coming from PHPStan.

The rules aim for parity with Coder 9.

Quick start

You need PHP 8.1 or later and Mago 1.58.1 or later.

composer require --dev carthage-software/mago "drupal/mago:^1.0@alpha"

Then create a mago.toml file next to composer.json:

extends = "vendor/drupal/mago/drupal.mago.toml"
# The lowest PHP version that the project supports.
php-version = "8.3"

[source]
# The project's own code.
paths = ["web/modules/custom", "web/themes/custom"]
# Read by the analyzer for their classes and functions, and not checked.
includes = ["vendor", "web/core", "web/modules/contrib"]

A module, theme or profile with its own repository uses paths = ["."] and includes = ["vendor", "web"]. For a module cloned into a site and for a Drupal core checkout, see Install.

Then run the linter and the analyzer:

vendor/bin/mago lint
vendor/bin/mago analyze

The next pages have the rest: what the config files set, the worker's arguments and the fix levels.

Acknowledgements

This extension is based on Coder and phpstan-drupal. The checks of Coder's Drupal and DrupalPractice standards are ported to Mago's linter, and the types and rules of phpstan-drupal to Mago's analyzer.