Configuration

Mago is configured using a mago.toml file in the root of your project. 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.

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

Option	Type	Default	Description
php-version	string	"8.1"	The version of PHP to use for parsing and analysis.
allow-unsupported-php-version	boolean	false	Allow Mago to run on unsupported PHP versions. Not recommended.
threads	integer	(logical CPUs)	The number of threads to use for parallel tasks.
stack-size	integer	(see below)	The stack size in bytes for each thread. Defaults to 2MB, with a minimum of 2MB and a maximum of 8MB.

[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

Option	Type	Default	Description
paths	string[]	[]	Directories or glob patterns for your source code. These files will be analyzed, linted, and formatted. If empty, the entire workspace is scanned.
includes	string[]	[]	Directories or glob patterns for dependencies (e.g., vendor). These files are parsed for symbols and types but are NOT analyzed, linted, or formatted.
excludes	string[]	[]	Glob patterns or paths to completely exclude from all tools. These files won't be processed or parsed at all.
extensions	string[]	["php"]	File extensions to treat as PHP files.

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/**"]

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.

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]

Flag, Alias(es)	Description
--show <SECTION>	Display only a specific section of the configuration. Values: source, linter, formatter, analyzer
--default	Show the default configuration values instead of the current merged configuration.
--schema	Output JSON schema instead of configuration values. Useful for documentation and IDE integration.
-h, --help	Print help information.