# Mago for Drupal

A [Mago](<https://mago.carthage.software>) extension that adds [Drupal's coding standards](<https://project.pages.drupalcode.org/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](<https://project.pages.drupalcode.org/mago/rules/index.md>).
- **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](<https://project.pages.drupalcode.org/mago/analyzer/index.md>).
- **Fixes** work the way phpcbf fixes Coder's sniffs. Many rules have one, and `mago lint --fix` applies them. See [Fixes](<https://project.pages.drupalcode.org/mago/setup/fixes/index.md>).
- **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](<https://project.pages.drupalcode.org/mago/coder/index.md>). The extension can also read the `phpcs:ignore` comments themselves, see [phpcs ignores](<https://project.pages.drupalcode.org/mago/coder/phpcs-ignores/index.md>).
- **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](<https://project.pages.drupalcode.org/mago/phpstan/index.md>).

The rules aim for parity with [Coder 9](<https://www.drupal.org/project/coder/releases/9.0.0>).

## 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](<https://project.pages.drupalcode.org/mago/setup/install/index.md>).

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](<https://project.pages.drupalcode.org/mago/setup/configuration/index.md>) set, the [worker's arguments](<https://project.pages.drupalcode.org/mago/setup/worker/index.md>) and the [fix levels](<https://project.pages.drupalcode.org/mago/setup/fixes/index.md>).

## Acknowledgements

This extension is based on [Coder](<https://www.drupal.org/project/coder>) and [phpstan-drupal](<https://github.com/mglaman/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.