Problem/Motivation

There is a super fast PHP formatter, linter and analyzer written in Rust: mago https://github.com/carthage-software/mago . A Drupal preset for formatting Drupal code has already been committed in Mago, yay!

The problem now is that Mago fmt does not support doc comments yet for example: https://github.com/carthage-software/mago/issues/906

So we cannot replace PHPCS with Mago, and probably not for a long time. It lacks some sniffs we have in Coder and might never implement them. What we can do is establish best practices how to run Mago and Coder/PHPCS together.

Proposed resolution

  • Use mago fmt and PHPCS with Coder for everything that mago does not check yet
  • Define a new PHPCS Standard for that in Coder: DrupalMago
    • It includes only sniffs that mago does not cover
  • Add a new helper CLI command to generate a Mago config from a PHPCS config
  • Add a new helper CLI command that runs 4 parts:
    • mago fmt
    • mago lint
    • mago analyze
    • phpcs
  • Add documentation about Drupal best practices what can be used from Mago

Remaining tasks

Discuss the best approaches and ideas how we can use Mago for Drupal, then implement helpers.

API changes

None.

Issue fork coder-3585617

Command icon Show commands

Start within a Git clone of the project using the version control instructions.

Or, if you do not have SSH keys set up on git.drupalcode.org:

Comments

klausi created an issue.

amateescu’s picture

I like this plan a lot :) Also wanted to point out that I've created a ddev addon for mago: https://addons.ddev.com/addons/amateescu/ddev-mago

But maybe we should try to get it into ddev's web container directly...

amateescu’s picture

And custom rules might become a reality quite soon: https://github.com/carthage-software/mago/pull/1663

klausi’s picture

I like that you can install Mago with composer, so DDEV does not have to do anything and you can run it the same way as PHPCS. https://mago.carthage.software/guide/installation#composer-php-project

Also happy to discuss Mago at Drupal Dev Days, I'm doing a session there https://devdays2026.drupal.org.gr/drupal-developer-days-athens-2026/sess...

johnatas’s picture

Hi,

Thanks klausi for your session at Drupal Dev Days, it was really great.

Thanks amateescu for the ddev addon. On my side, I’m using GrumPHP to ensure code quality on my Drupal projects (and to run all my linters/analyzers/formatters in parallel).

There was already an issue opened to add Mago as a task in GrumPHP, and I’ve just opened a PR in case it might be of interest to some of you: https://github.com/phpro/grumphp/pull/1216

wim leers’s picture

Anything I can do with adopting this early in Canvas that would help y’all here? 🤓

Canvas follows Drupal core’s coding standaards, disabled a dozen of the most boiler-plate-y rules, and adds a bunch of extra ones (including some custom rules). It also complies with PHPStan level 8. So I suspect it might be a helpful testing ground?