title: Analyzer configuration Reference

Configuration reference

Mago's analyzer is highly configurable, allowing you to tailor the analysis to your project's specific needs. All settings go under the [analyzer] table in your mago.toml file.

[analyzer]
# Ignore a specific error code across the whole project
ignore = ["mixed-argument"]

# Ignore an error code only in specific paths
ignore = [
  "mixed-argument",
  { code = "missing-return-type", in = "tests/" },
]

# Use a baseline file to ignore existing issues
baseline = "analyzer-baseline.toml"

General options

:::tip Tool-Specific Excludes The excludes option here is additive to the global source.excludes defined in the [source] section of your configuration. Files excluded globally will always be excluded from analysis, and this option allows you to exclude additional files from the analyzer specifically.

For example:

[source]
excludes = ["cache/**"]  # Excluded from ALL tools

[analyzer]
excludes = ["tests/**/*.php"]  # Additionally excluded from analyzer only

:::

Path-scoped ignoring

The ignore option accepts three formats:

Plain string — ignore a code everywhere:

ignore = ["missing-return-type"]

Object with single path — ignore a code only in a specific directory or file:

ignore = [
  { code = "missing-return-type", in = "tests/" },
]

Object with multiple paths — ignore a code in several locations:

ignore = [
  { code = "missing-return-type", in = ["tests/", "src/Legacy/"] },
]

All three formats can be mixed in the same ignore list:

ignore = [
  "mixed-argument",
  { code = "missing-return-type", in = "tests/" },
  { code = "unused-parameter", in = ["tests/", "src/Generated/"] },
]

Paths are matched as prefixes against relative file paths from the project root. Both "tests" and "tests/" will match all files under the tests directory.

:::tip Path-scoped ignoring is different from excludes:

• excludes removes files from analysis entirely — they won't be parsed for type information.
• ignore with in still analyzes the files but suppresses specific issue codes in the output. :::

Feature flags

These flags control specific, powerful analysis capabilities.

Property initialization

These options control how the analyzer checks property initialization.

How it works

When check-property-initialization is enabled, the analyzer reports:

• missing-constructor: Classes with typed properties that have no constructor to initialize them
• uninitialized-property: Typed properties not initialized in the constructor

The class-initializers setting allows you to specify additional methods that should be treated as initializers. Properties initialized in these methods count as "definitely initialized", just like in __construct. This is useful for frameworks that use lifecycle methods like:

• PHPUnit's setUp() method for test classes
• Framework-specific boot() or initialize() methods

Example

[analyzer]
# Treat setUp as a class initializer (for PHPUnit tests)
class-initializers = ["setUp", "initialize", "boot"]

With this configuration, the following code won't trigger false positives:

class MyTest extends TestCase
{
    private string $name;

    protected function setUp(): void
    {
        // Property initialized in setUp - no error reported
        $this->name = "test";
    }
}

Enabling property initialization checks

Property initialization checking is disabled by default. To enable it:

[analyzer]
check-property-initialization = true

This enables both missing-constructor and uninitialized-property issues.

Exception filtering

When check-throws is enabled, you can fine-tune which exceptions should be ignored using these options:

How it works

• unchecked-exceptions: When you add an exception class here, that exception and all classes that extend it will be ignored. This is useful for ignoring entire exception hierarchies, like all logic exceptions.

• unchecked-exception-classes: When you add an exception class here, only that exact class is ignored. Subclasses and parent classes are still checked. This is useful when you want to ignore a specific exception without affecting related exceptions.

Example

[analyzer]
check-throws = true

# Ignore LogicException and ALL its subclasses:
# - InvalidArgumentException
# - OutOfRangeException
# - DomainException
# - etc.
unchecked-exceptions = [
    "LogicException",
    "Psl\\Type\\Exception\\ExceptionInterface",
]

# Ignore ONLY this specific exception class (not its parent or child classes)
unchecked-exception-classes = [
    "Psl\\File\\Exception\\FileNotFoundException",
]

In this example:

• Any unhandled LogicException or its subclasses (like InvalidArgumentException) won't be reported
• Any class implementing Psl\Type\Exception\ExceptionInterface won't be reported
• Only the exact Psl\File\Exception\FileNotFoundException is ignored, but other file exceptions would still be reported

:::tip When to use which option Use unchecked-exceptions when you want to ignore an entire category of exceptions, such as logic errors that indicate programming mistakes rather than runtime issues.

Use unchecked-exception-classes when you want to ignore a specific exception but still want to track its parent or sibling exceptions. :::

Experimental API detection

When check-experimental is enabled, the analyzer reports warnings when code marked with [@experimental](https://github.com/experimental) is used from a non-experimental context. This helps teams manage unstable APIs that may change or be removed without notice. Available since Mago 1.19.0.

How it works

Mark classes, interfaces, traits, or functions with the [@experimental](https://github.com/experimental) PHPDoc tag:

/** [@experimental](https://github.com/experimental) */
class UnstableApi {
    public function doSomething(): void {}
}

/** [@experimental](https://github.com/experimental) */
function beta_feature(): void {}

The analyzer will then warn when these symbols are used from non-experimental code:

// Warning: Usage of experimental class-like `UnstableApi`.
new UnstableApi();

// Warning: Usage of experimental function `beta_feature`.
beta_feature();

// Warning: Usage of experimental class-like `UnstableApi`.
class MyService extends UnstableApi {}

Suppressing warnings

Usage from an experimental context is allowed without warnings:

/** [@experimental](https://github.com/experimental) */
function also_experimental(): void {
    // OK — both caller and callee are experimental
    new UnstableApi();
    beta_feature();
}

/** [@experimental](https://github.com/experimental) */
class ExperimentalConsumer extends UnstableApi {
    // OK — the class itself is experimental
}

class StableService {
    /** [@experimental](https://github.com/experimental) */
    public function experimentalMethod(): void {
        // OK — the method is experimental
        new UnstableApi();
    }
}

Enabling experimental checks

[analyzer]
check-experimental = true

Plugins

Plugins extend the analyzer with specialized type information for libraries and frameworks. They provide accurate type inference for functions that would otherwise return generic types.

Available plugins

How plugins work

Plugins provide "type providers" that give the analyzer precise type information for library functions. For example, the stdlib plugin knows that:

• array_filter($array) returns the same array type but potentially with fewer elements
• json_decode($json, true) returns array<string, mixed> when the second argument is true
• strlen($string) returns int<0, max>

Without plugins, these functions would return less precise types like mixed or array.

Example configurations

Using default plugins only

By default, the stdlib plugin is enabled:

[analyzer]
# No configuration needed - stdlib is enabled by default

Enabling additional plugins

[analyzer]
plugins = ["psl", "flow-php", "psr-container"]

Disabling all plugins

[analyzer]
disable-default-plugins = true

Using only specific plugins

[analyzer]
disable-default-plugins = true
plugins = ["psl"]  # Only enable PSL, not stdlib

:::tip Plugin aliases You can use any of the plugin aliases for convenience. For example, plugins = ["std"] is equivalent to plugins = ["stdlib"]. :::

Strict mode

The analyzer can be configured to be more or less strict depending on your project's needs. This section describes how to configure the analyzer for maximum strictness.

Maximum strictness configuration

For the strictest possible analysis, use the following configuration:

[analyzer]
# Enable all checks
find-unused-expressions = true
find-unused-definitions = true
analyze-dead-code = true
check-throws = true
check-missing-override = true
find-unused-parameters = true
check-missing-type-hints = true
check-closure-missing-type-hints = true
check-arrow-function-missing-type-hints = true
enforce-class-finality = true
require-api-or-internal = true
check-experimental = true

# Enable strict checks
strict-list-index-checks = true
no-boolean-literal-comparison = true

# Disable lenient behaviors
allow-possibly-undefined-array-keys = false
trust-existence-checks = false

Strictness options explained

Type hint enforcement

Array access strictness

Runtime check behavior

When trust-existence-checks is enabled (the default), the analyzer narrows types based on runtime existence checks:

function process(object $obj): mixed
{
    // With trust-existence-checks = true (default):
    // No warning - method existence is verified at runtime
    if (method_exists($obj, 'toArray')) {
        return $obj->toArray();
    }

    // With trust-existence-checks = false:
    // Warning reported - explicit type hints required
    return null;
}

Code quality checks

Exception handling

Lenient mode

For a more lenient analysis (useful for legacy codebases or gradual adoption), use:

[analyzer]
# Disable strict checks
check-missing-type-hints = false
strict-list-index-checks = false
no-boolean-literal-comparison = false
enforce-class-finality = false
require-api-or-internal = false

# Enable lenient behaviors
allow-possibly-undefined-array-keys = true
trust-existence-checks = true

# Optionally disable some checks
check-throws = false

:::tip Gradual adoption When introducing Mago to an existing codebase, start with lenient settings and a baseline. Gradually enable stricter options as you improve the codebase. :::

Performance tuning

The analyzer uses internal thresholds to balance analysis depth against performance. These thresholds control how deeply the type inference engine explores complex logical formulas. All settings go under [analyzer.performance] in your mago.toml file.