title: Configuration Reference

Configuration

Mago is configured using a mago.toml file. You can generate a default configuration file using the mago init command.

This page details the global configuration options and the [source] section. For tool-specific options, see the links at the bottom of this page.

Configuration File Discovery

When no --config flag is provided, Mago searches for a configuration file (mago.toml, mago.yaml, or mago.json) in the following locations, in order:

1. Workspace directory — the current working directory (or the path given by --workspace)
2. $XDG_CONFIG_HOME — if the environment variable is set (e.g., $XDG_CONFIG_HOME/mago.toml)
3. $HOME/.config — the default XDG config directory (e.g., ~/.config/mago.toml)
4. $HOME — the user's home directory (e.g., ~/mago.toml)

The first file found wins. This allows you to have a global configuration in ~/.config/mago.toml that applies when no project-level configuration exists.

Global Options

These options are set at the root of your mago.toml file.

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

[source] Section

This section configures how Mago discovers and processes files in your project.

Understanding paths, includes, and excludes

Mago distinguishes between your code (what you want to check and format) and dependencies (code you need for context but don't want to modify):

• paths = Your source code - files that Mago will actively process:

  • ✓ Analyzed for type errors and logic issues
  • ✓ Linted for code quality and style violations
  • ✓ Formatted to match your code style

• includes = Dependencies and vendor code - files that Mago will parse for context only:

  • ✓ Parsed to understand symbols, classes, functions, and types
  • ✗ NOT analyzed for issues
  • ✗ NOT linted
  • ✗ NOT formatted
  • Example: vendor directory, third-party libraries, framework code

• excludes = Paths or patterns to completely skip:

  • Applies globally to ALL tools (linter, formatter, analyzer, guard)
  • Files matching these patterns won't be processed or parsed at all
  • Example: cache directories, build artifacts, generated files

:::tip If a file matches both paths and includes, the more specific pattern takes precedence:

• Exact file paths (e.g., src/b.php) are most specific
• Deeper directory paths (e.g., src/foo/bar/) are more specific than shallow ones (e.g., src/)
• Directory paths are more specific than glob patterns (e.g., src/*.php)

If patterns have equal specificity, includes takes precedence. This allows you to explicitly override the file type for specific paths when needed. :::

Basic Example

[source]
# Your application code - will be analyzed, linted, and formatted
paths = ["src", "tests"]

# Vendor dependencies - only parsed for type information
includes = ["vendor"]

# Completely ignored by all tools
excludes = ["cache/**", "build/**", "var/**"]

# File extensions to treat as PHP
extensions = ["php"]

Glob Pattern Support

Both paths, includes, and excludes support glob patterns:

[source]
# Use glob patterns to target specific files
paths = ["src/**/*.php"]
includes = ["vendor/symfony/**/*.php"]  # Only Symfony from vendor
excludes = [
    "**/*_generated.php",      # Any generated file
    "**/tests/**",             # All test directories
    "src/Legacy/**",           # Specific legacy code
]

Configuration Reference

Glob Settings

The [source.glob] section controls how glob patterns are matched. Available since Mago 1.19.0.

[source.glob]
# When true, `*` does not match `/` in paths. Use `**` for recursive matching.
# e.g., `src/*/Test` matches `src/foo/Test` but NOT `src/foo/bar/Test`.
literal-separator = true

# Match patterns case-insensitively.
case-insensitive = false

# Whether `\` escapes special characters in patterns.
backslash-escape = true

# Whether empty alternates are allowed, e.g., `{,a}` matches "" and "a".
empty-alternates = false

:::tip New projects created with mago init automatically set literal-separator = true, which is the recommended setting. It makes * behave like most users expect (matching a single directory level, like .gitignore). :::

Tool-Specific Excludes

In addition to the global excludes option, each tool (linter, formatter, analyzer, guard) has its own excludes option for tool-specific exclusions.

Tool-specific excludes are additive - files are excluded if they match EITHER the global source.excludes OR the tool-specific excludes.

[source]
paths = ["src", "tests"]
excludes = ["cache/**"]  # Excluded from ALL tools

[analyzer]
# Additionally exclude test files from analysis only
# (they'll still be linted and formatted)
excludes = ["tests/**/*.php", "src/**/tests/**"]

[formatter]
# Additionally exclude auto-generated code from formatting only
# (it will still be analyzed and linted)
excludes = ["src/**/AutoGenerated/**/*.php"]

[linter]
# Additionally exclude database migrations from linting only
excludes = ["database/migrations/**"]

The linter also supports per-rule path exclusions, allowing you to skip individual rules for specific files or directories while still applying other rules. See the Linter Configuration Reference for details.

[linter.rules]
# Don't enforce static closures in test files
prefer-static-closure = { exclude = ["tests/"] }

:::tip Using mago list-files Use the mago list-files command to see which files will be processed:

# See all files in your project
mago list-files

# See which files the formatter will process
mago list-files --command formatter

# See which files the analyzer will process
mago list-files --command analyzer

This helps verify your paths, includes, and excludes configuration is working as expected. :::

[parser] Section

This section configures how Mago parses PHP code, including lexer-level settings that affect tokenization behavior.

Example

[parser]
enable-short-tags = false

Configuration Reference

When to Disable Short Open Tags

You might want to disable short open tags if:

• Your project contains XML files with .php extensions that use <?xml declarations
• You're working with template files that mix PHP and XML/HTML containing <? sequences
• Your coding standards require explicit <?php tags for clarity
• You want to match the behavior of PHP installations where short_open_tag is disabled

:::warning When enable-short-tags is false, sequences like <?xml version="1.0"?> will be treated as inline text rather than causing parse errors. However, any code using <? as a PHP open tag will no longer be recognized as PHP code. :::

Editor Integration

Mago can make file paths in diagnostic output clickable using OSC 8 terminal hyperlinks. When configured, clicking a file path in the terminal opens the file directly in your editor at the correct line and column.

This works in terminals that support OSC 8 hyperlinks, including iTerm2, Wezterm, Kitty, Windows Terminal, Ghostty, and others.

Auto-Detection

Mago automatically detects your editor when running inside a supported terminal. On macOS, this uses the __CFBundleIdentifier environment variable set by the running application. On other platforms, the TERM_PROGRAM variable is checked.

The following editors are automatically detected:

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

When auto-detection succeeds, clickable file paths work out of the box with no configuration needed.

Manual Configuration

If auto-detection doesn't work for your setup, or you want to override it, you can set the editor URL explicitly.

The MAGO_EDITOR_URL environment variable takes the highest precedence:

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

The editor-url option in mago.toml takes precedence over auto-detection but is overridden by the environment variable:

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

Precedence

The editor URL is resolved in the following order (first match wins):

1. MAGO_EDITOR_URL environment variable
2. editor-url in mago.toml
3. Auto-detection from terminal environment

Supported Placeholders

Editor URL Templates

:::tip Hyperlinks are only rendered when output is sent to a terminal with colors enabled. They are automatically disabled when output is piped or when --colors=never is used, so they won't interfere with scripts or CI pipelines. :::

Supported Formats

Clickable file paths are supported in the following reporting formats:

• rich (default), medium, short — file paths in diagnostic headers
• emacs — file paths at the start of each line

Machine-readable formats (json, github, gitlab, checkstyle, sarif) are not affected.

Tool-Specific Configuration

For details on configuring the linter, formatter, and analyzer, see their respective reference pages:

• Linter Configuration
• Formatter Configuration
• Analyzer Configuration
• Guard Configuration

The config Command

The mago config command is a utility to display the final, merged configuration that Mago is using for the current project.

This is invaluable for debugging your setup, as it shows you the result of combining your mago.toml file, any environment variables, and the built-in defaults.

Usage

Running the command without any options will print the entire configuration object as a pretty-printed JSON object.

mago config

You can inspect a specific part of the configuration using the --show flag.

# Show only the [linter] configuration
mago config --show linter

# Show only the [formatter] configuration
mago config --show formatter

You can also output the JSON schema for the configuration using the --schema flag. This is useful for generating documentation, IDE integration, or validation tooling.

# Output the JSON schema for the entire configuration
mago config --schema

# Output the JSON schema for a specific section
mago config --schema --show linter

Command reference

:::tip For global options that can be used with any command, see the Command-Line Interface overview. Remember to specify global options before the config command. :::

Usage: mago config [OPTIONS]