Configuration

Mago lit sa configuration depuis un seul fichier, généralement mago.toml à la racine de votre projet. Lancez mago init pour en générer un, ou écrivez-le à la main.

Cette page couvre la découverte de la configuration, la directive extends, les options globales et les sections [source] et [parser]. Les options spécifiques à chaque outil sont documentées sur la page de référence de l'outil concerné.

Découverte

Lorsque vous ne passez pas --config, Mago cherche un fichier de configuration dans cet ordre :

1. Le répertoire de travail (le répertoire courant, ou le chemin donné par --workspace).
2. $XDG_CONFIG_HOME s'il est défini, par exemple $XDG_CONFIG_HOME/mago.toml.
3. $HOME/.config, par exemple ~/.config/mago.toml.
4. $HOME, par exemple ~/mago.toml.

Dans chaque emplacement, il cherche d'abord mago.{toml,yaml,yml,json}, puis mago.dist.{toml,yaml,yml,json}. La précédence des formats au sein d'un même répertoire est toml > yaml > yml > json. Le premier fichier trouvé l'emporte, ce qui vous permet de garder une configuration globale dans ~/.config/mago.toml pour les projets qui n'en ont pas localement.

Partager une configuration avec extends

Disponible depuis Mago 1.25. Les versions antérieures ignorent silencieusement la directive.

La directive extends permet à une configuration de s'appuyer sur d'autres sans copier-coller. Pratique quand plusieurs projets partagent un standard commun.

# Single parent
extends = "vendor/some-org/mago-config/mago.toml"

# Or a list, applied left-to-right; each later layer overrides earlier ones
extends = [
  "vendor/some-org/mago-config",     # directory: mago.{toml,yaml,yml,json} inside
  "configs/strict.json",              # mixing formats is fine
  "../shared/team-defaults.toml",
]

# This file's own keys override anything from the layers above
php-version = "8.3"

Résolution

Les chemins absolus sont utilisés tels quels. Les chemins relatifs sont résolus par rapport au répertoire du fichier qui déclare extends, et non par rapport au répertoire de travail courant. Ainsi, mago --config some/dir/config.toml avec extends = "base.toml" cherche some/dir/base.toml.

Les entrées de fichier doivent exister et utiliser une extension reconnue (.toml, .yaml, .yml, .json). Les entrées de répertoire sont parcourues à la recherche de mago.{toml,yaml,yml,json} selon cette précédence ; un répertoire sans fichier reconnu est ignoré avec un avertissement plutôt que de faire échouer la construction.

Précédence effective

Les couches sont fusionnées de la plus profonde à la plus superficielle, la dernière l'emportant :

1. Valeurs par défaut intégrées.
2. Chaque couche extends, récursivement. Le extends propre à un parent est résolu avant que ses clés ne s'appliquent.
3. Les clés du fichier propriétaire.
4. Les variables d'environnement MAGO_* pour les scalaires pris en charge.
5. Les drapeaux CLI tels que --php-version, --threads.

Sémantique de fusion

Par clé de premier niveau :

• Les tables et objets sont fusionnés en profondeur. Un enfant peut surcharger une seule clé d'une table imbriquée sans redéfinir toute la table.
• Les tableaux comme source.excludes et les listes exclude par règle sont concaténés, parent en premier. Si une configuration de base exclut vendor/, vous gardez cette exclusion et ajoutez la vôtre.
• Les scalaires (chaînes, nombres, booléens) sont écrasés par l'enfant.

# base.toml
threads = 4
[source]
excludes = ["vendor", "node_modules"]

# project mago.toml
extends = "base.toml"
threads = 8
[source]
excludes = ["build"]   # appended -> ["vendor", "node_modules", "build"]

Les cycles sont détectés via le suivi des chemins canoniques et déclenchent une erreur claire au lieu de récurer indéfiniment. L'héritage en losange (A étend B et C, qui étendent tous deux D) traite D une seule fois et fonctionne sans souci. Les couches peuvent mélanger les formats librement ; chacune est analysée par son propre driver et fusionnée à un niveau de valeur générique avant que le document final ne soit validé contre le schéma.

Options globales

Ces clés se trouvent à la racine de mago.toml.

version = "1"
php-version = "8.2"
threads = 8
stack-size = 8388608     # 8 MiB
editor-url = "phpstorm://open?file=%file%&line=%line%&column=%column%"

Épinglage de version

Épingler la version fait remonter rapidement les divergences entre le binaire installé et les attentes du projet, plutôt que de produire silencieusement une sortie différente.

Trois niveaux d'épinglage :

• Épinglage majeur (version = "1") : tout 1.x.y satisfait l'épinglage. Une montée vers 2.x est une erreur fatale, car une nouvelle version majeure peut introduire des défauts incompatibles, des changements de schéma ou de comportement de règles. C'est ce que mago init écrit par défaut.
• Épinglage mineur (version = "1.25") : tout 1.25.y satisfait l'épinglage. Une divergence vers un mineur différent émet un avertissement ; une divergence majeure reste fatale.
• Épinglage exact (version = "1.25.2") : toute divergence émet un avertissement ; une divergence majeure reste fatale.

L'avertissement peut être réduit au silence avec --no-version-check, la variable d'environnement MAGO_NO_VERSION_CHECK, ou no-version-check = true dans la configuration. Aucun de ces moyens n'affecte la divergence de version majeure, qui est tout l'intérêt de l'épinglage.

Pour synchroniser le binaire installé avec l'épinglage du projet :

mago self-update --to-project-version

Pour les épinglages exacts, cela résout directement vers ce tag de release. Pour les épinglages majeurs ou mineurs, Mago parcourt les releases GitHub récentes et installe la plus haute qui satisfait l'épinglage. Ainsi, version = "1" avec 2.0 déjà sortie installe quand même la dernière release 1.x sans vous tirer en avant.

version est actuellement optionnel. Une future version de Mago pourrait commencer à émettre un avertissement quand il est absent, afin de préparer les projets à l'éventuelle montée vers la 2.0.

[source]

La section [source] contrôle la manière dont Mago découvre et traite les fichiers.

Trois catégories de chemins

Mago distingue votre code, le code tiers et le code à ignorer entièrement :

• paths sont vos fichiers source. Mago les analyse, les linte et les formate.
• includes sont les dépendances (généralement vendor). Mago les analyse pour pouvoir résoudre les symboles et les types, mais ne les analyse, ne les linte ni ne les réécrit jamais.
• excludes sont des chemins ou des globs que Mago ignore entièrement. Ils s'appliquent à chaque outil.

Si un fichier correspond à la fois à paths et à includes, le motif le plus spécifique l'emporte. Les chemins de fichier exacts sont les plus spécifiques, puis les chemins de répertoires plus profonds, puis les moins profonds, puis les motifs glob. Quand les motifs sont également spécifiques, includes l'emporte, ce qui vous permet de marquer explicitement un chemin comme dépendance.

[source]
paths     = ["src", "tests"]
includes  = ["vendor"]
excludes  = ["cache/**", "build/**", "var/**"]
extensions = ["php"]

Les motifs glob fonctionnent dans les trois listes :

[source]
paths    = ["src/**/*.php"]
includes = ["vendor/symfony/**/*.php"]   # only Symfony from vendor
excludes = [
  "**/*_generated.php",
  "**/tests/**",
  "src/Legacy/**",
]

Référence

Réglages des globs

[source.glob] ajuste la façon dont les globs correspondent. Disponible depuis 1.19.

[source.glob]
literal-separator = true     # `*` does not match `/`; use `**` for recursion
case-insensitive  = false
backslash-escape  = true     # `\` escapes special characters
empty-alternates  = false    # `{,a}` matches "" and "a" when true

Les projets générés par mago init mettent literal-separator = true. Cela fait que * se comporte comme la plupart des utilisateurs s'y attendent, en ne correspondant qu'à un seul niveau de répertoire, comme dans .gitignore.

Exclusions par outil

Chaque outil a son propre excludes optionnel. Ils sont additifs : un fichier est exclu s'il correspond à la liste globale ou à la liste spécifique à l'outil.

[source]
paths    = ["src", "tests"]
excludes = ["cache/**"]            # all tools

[analyzer]
excludes = ["tests/**/*.php"]      # only the analyzer

[formatter]
excludes = ["src/**/AutoGenerated/**/*.php"]

[linter]
excludes = ["database/migrations/**"]

Le linter prend également en charge des exclusions de chemin par règle, utiles quand vous voulez qu'une règle ignore un chemin alors que le reste continue à s'appliquer. Les motifs glob y nécessitent Mago 1.20 ou plus récent. La référence complète se trouve sur la page de configuration du linter.

[linter.rules]
prefer-static-closure = { exclude = ["tests/"] }
no-global             = { exclude = ["**/*Test.php"] }

Utilisez mago list-files pour vérifier quels fichiers Mago va traiter. mago list-files --command formatter montre ce que le formateur va toucher, --command analyzer montre la vue de l'analyseur, et ainsi de suite.

[parser]

[parser]
enable-short-tags = false

Désactivez les balises ouvertes courtes lorsque vos fichiers .php contiennent des déclarations littérales <?xml ou des fragments de modèles qui ne sont pas du PHP. Avec enable-short-tags = false, des séquences telles que <?xml version="1.0"?> sont traitées comme du texte intégré plutôt que comme des erreurs d'analyse. Le compromis : tout code qui s'appuie sur <? comme balise d'ouverture PHP ne sera plus reconnu.

Intégration éditeur

Mago peut afficher les chemins de fichiers dans la sortie de diagnostic sous forme de liens hypertextes OSC 8. Cliquez sur le chemin dans votre terminal et votre éditeur ouvre le fichier à la bonne ligne et la bonne colonne. Les terminaux pris en charge incluent iTerm2, WezTerm, Kitty, Windows Terminal, Ghostty, et quelques autres.

Mago détecte automatiquement l'éditeur en cours d'exécution quand c'est possible. Sur macOS, il lit __CFBundleIdentifier ; ailleurs il vérifie TERM_PROGRAM. Les éditeurs suivants sont reconnus directement :

• PhpStorm, IntelliJ IDEA, WebStorm
• VS Code, VS Code Insiders
• Zed
• Sublime Text

Si la détection automatique échoue, configurez l'URL explicitement. La précédence est de type premier-trouvé-l'emporte :

1. Variable d'environnement MAGO_EDITOR_URL.
2. editor-url dans mago.toml.
3. Détection automatique.

export MAGO_EDITOR_URL="vscode://file/%file%:%line%:%column%"

editor-url = "phpstorm://open?file=%file%&line=%line%&column=%column%"

Modèles courants :

Les liens hypertextes ne sont rendus que lorsque la sortie est un terminal avec les couleurs activées. Ils sont automatiquement supprimés quand la sortie est redirigée vers un pipe ou que --colors=never est utilisé, afin de ne pas interférer avec les scripts ou la CI.

Les liens hypertextes apparaissent dans les formats de rapport rich (par défaut), medium, short et emacs. Les formats lisibles par machine (json, github, gitlab, checkstyle, sarif) ne sont pas affectés.

Configuration spécifique aux outils

Chaque outil a sa propre page de référence couvrant ses options :

• Linter
• Formateur
• Analyseur
• Guard

Inspecter la configuration fusionnée

mago config affiche la configuration que Mago utilise réellement, après fusion des défauts, de chaque couche extends, des variables d'environnement et des drapeaux CLI. Pratique quand quelque chose ne se comporte pas comme prévu.

mago config                       # full config as pretty-printed JSON
mago config --show linter         # only the [linter] section
mago config --show formatter
mago config --default             # the built-in defaults
mago config --schema              # JSON Schema for the whole config
mago config --schema --show linter

Les drapeaux globaux doivent venir avant config. Voir l'aperçu CLI pour la liste complète.