# 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](<https://project.pages.drupalcode.org/mago/setup/configuration/index.md>).
- `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](<https://github.com/amateescu/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](<https://project.pages.drupalcode.org/mago/setup/worker/index.md#a-config-file-outside-the-project>).

## Next

- [Configuration](<https://project.pages.drupalcode.org/mago/setup/configuration/index.md>): what the preset sets, and how to change it.
- [The worker](<https://project.pages.drupalcode.org/mago/setup/worker/index.md>): the PHP process that runs the Drupal rules, its arguments and its cache.
- [Fixes](<https://project.pages.drupalcode.org/mago/setup/fixes/index.md>): what `mago lint --fix` and `mago format` change.