Skip to content

Install

Install Mago and the extension with Composer:

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

The @alpha flag lets Composer install an alpha release. It's needed while drupal/mago doesn't have a stable release.

Create mago.toml

Create a mago.toml file next to composer.json. Its content depends on the kind of project.

A site

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

[source]
# The code to check.
paths = ["web/modules/custom", "web/themes/custom"]
# Code that is only read, so that the analyzer knows its classes and functions.
includes = ["vendor", "web/core", "web/modules/contrib"]

A module, theme or profile

This is for a project with its own repository, such as a project on drupal.org. GitLab CI and ddev-drupal-contrib install the Composer packages into the project's directory and build the site in web. The file checks the project's directory and reads the other two:

extends = "vendor/drupal/mago/drupal.mago.toml"
php-version = "8.3"

[source]
paths = ["."]
includes = ["vendor", "web"]

Drupal core

In a core checkout, extend the preset for core. It sets the paths itself:

extends = "vendor/drupal/mago/drupal-core.mago.toml"

Run Mago

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

Use vendor/bin/mago, not a Mago installed another way, such as with Homebrew. A different version can stop mago analyze with Unsupported analyzer protocol version.

What the settings do

  • extends loads the package's settings: Drupal's file extensions, the worker with the Drupal rules, and Mago's own rules set up for Drupal's standard. See Configuration.
  • paths lists the code to check. Mago doesn't check any file while it isn't set.
  • includes lists code that is read and not checked. Without it, the analyzer reports the classes and functions of core, of contributed modules and of the packages in vendor as unknown. Don't list a directory that holds one of the paths. Mago's linter and formatter skip everything under an included directory.

A module cloned into a site

The mago.toml of a module is written for the module's own repository. The same module can also be cloned into a site, as web/modules/contrib/foo. It doesn't have a vendor directory there, so Mago can't run from the module's directory. There are two ways to check it:

  • From the site. Give the site a mago.toml and pass the module as a path: vendor/bin/mago lint web/modules/contrib/foo. The site's settings apply, and the module's mago.toml isn't read.
  • With ddev-drupal-dev. The ddev-drupal-dev add-on for DDEV is for work on core and contributed modules in a core checkout. Run ddev mago lint in the module's directory, and the module's own mago.toml is used.

When vendor isn't next to mago.toml

Two paths in the setup point into vendor: the extends path and the script of the worker. Both are relative to the directory of mago.toml. Change the first one, and set the second one under [extension-hosts.drupal]:

extends = "../../vendor/drupal/mago/drupal.mago.toml"

[extension-hosts.drupal]
command = ["php", "-d", "xdebug.mode=off", "-d", "pcov.enabled=0", "../../vendor/drupal/mago/resources/worker.php"]

To start the worker in another directory, see A config file outside the project.

Next

  • Configuration: what the preset sets, and how to change it.
  • The worker: the PHP process that runs the Drupal rules, its arguments and its cache.
  • Fixes: what mago lint --fix and mago format change.