Struct Settings 

pub struct Settings {

    pub version: PHPVersion,
    pub find_unused_expressions: bool,
    pub find_unused_definitions: bool,
    pub find_overly_wide_return_types: bool,
    pub analyze_dead_code: bool,
    pub memoize_properties: bool,
    pub allow_possibly_undefined_array_keys: bool,
    pub check_throws: bool,
    pub unchecked_exceptions: WordSet,
    pub unchecked_exception_classes: WordSet,
    pub check_missing_override: bool,
    pub find_unused_parameters: bool,
    pub strict_list_index_checks: bool,
    pub strict_array_index_existence: bool,
    pub allow_array_truthy_operand: bool,
    pub no_boolean_literal_comparison: bool,
    pub enforce_class_finality: bool,
    pub require_api_or_internal: bool,
    pub check_missing_type_hints: bool,
    pub check_closure_missing_type_hints: bool,
    pub check_arrow_function_missing_type_hints: bool,
    pub allow_implicit_pipe_callable_types: bool,
    pub register_super_globals: bool,
    pub use_colors: bool,
    pub diff: bool,
    pub trust_existence_checks: bool,
    pub class_initializers: Vec<ClassInitializer>,
    pub check_property_initialization: bool,
    pub check_use_statements: bool,
    pub check_experimental: bool,
    pub check_name_casing: bool,
    pub allow_side_effects_in_conditions: bool,
    pub saturation_complexity_threshold: u16,
    pub disjunction_complexity_threshold: u16,
    pub negation_complexity_threshold: u16,
    pub consensus_limit_threshold: u16,
    pub formula_size_threshold: u16,
    pub string_combination_threshold: u16,
    pub integer_combination_threshold: u16,
    pub array_combination_threshold: u16,
    pub loop_assignment_depth_threshold: u8,
}

Configuration settings that control the behavior of the Mago analyzer.

This struct allows you to enable/disable specific checks, suppress categories of issues, and tune the analyzer’s performance and strictness.

Fields

version: PHPVersion

The target PHP version for the analysis.

find_unused_expressions: bool

Find and report expressions whose results are not used (e.g., $a + $b;). Defaults to false.

find_unused_definitions: bool

Find and report unused definitions (e.g., private methods that are never called). Defaults to false.

find_overly_wide_return_types: bool

Warn when a function’s declared return type contains a branch the body never actually returns (e.g. : string|false on a function that always returns a string). Defaults to false.

analyze_dead_code: bool

Analyze code that appears to be unreachable. Defaults to false.

memoize_properties: bool

Track the literal values of class properties when they are assigned. This improves type inference but may increase memory usage. Defaults to true.

allow_possibly_undefined_array_keys: bool

Allow accessing array keys that may not be defined without reporting an issue. Defaults to true.

check_throws: bool

Enable checking for unhandled thrown exceptions.

When true, the analyzer will report any exception that is thrown but not caught in a try-catch block or documented in a @throws tag.

This check is disabled by default (false) as it can be computationally expensive.

unchecked_exceptions: WordSet

Exceptions to ignore including all subclasses (hierarchy-aware).

When an exception class is in this set, any exception of that class or any of its subclasses will be ignored during check_throws analysis.

For example, adding LogicException will ignore LogicException, InvalidArgumentException, OutOfBoundsException, and all other subclasses.

unchecked_exception_classes: WordSet

Exceptions to ignore (exact class match only, not subclasses).

When an exception class is in this set, only that exact class will be ignored during check_throws analysis. Parent classes and subclasses are not affected.

check_missing_override: bool

Check for missing #[Override] attributes on overriding methods.

When enabled, the analyzer reports methods that override a parent method without the #[Override] attribute (PHP 8.3+).

Defaults to true.

find_unused_parameters: bool

Find and report unused function/method parameters.

When enabled, the analyzer reports parameters that are declared but never used within the function body.

Defaults to true.

strict_list_index_checks: bool

Enforce strict checks when accessing list elements by index.

When true, the analyzer requires that any integer used to access a list element is provably non-negative (e.g., of type int<0, max>). This helps prevent potential runtime errors from using a negative index.

When false (the default), any int is permitted as an index, offering more flexibility at the cost of type safety.

strict_array_index_existence: bool

Treat array/list indices that are not provably present as T|null and warn on access.

When true, reading a key from any array-like type whose presence is not guaranteed emits possibly-undefined-int-array-index / possibly-undefined-string-array-index and the resulting type is widened to T|null. This applies to list<T> (non-zero indices), non-required entries of array{...} shapes, and array<K, V> lookups with arbitrary keys. It lets === null, ??, and ??= checks behave correctly against PHP’s runtime semantics — PHP turns missing reads into null with an Undefined array key warning.

When false (the default), the analyzer keeps the looser behavior: the value is flagged as possibly-undefined internally but is not unioned with null and no warning is emitted. This is friendlier for typical PHP code that destructures or reads from arrays/lists by index without first asserting existence.

allow_array_truthy_operand: bool

Allow arrays as operands of logical operators (&&, ||, xor).

When true, the analyzer accepts an array on either side of a logical operator without emitting invalid-operand. PHP coerces empty arrays to false and non-empty arrays to true, mirroring the truthiness used by if ($array).

When false (the default), the analyzer flags array operands of &&/||/xor to call out the implicit bool coercion. This matches the long-standing default behavior; standalone if ($array) is still accepted and never produces this warning.

no_boolean_literal_comparison: bool

Disable comparisons to boolean literals (true/false).

When enabled, comparisons to boolean literals will not be reported as issues.

Defaults to false.

enforce_class_finality: bool

Enforce that concrete classes are declared final.

When enabled, the analyzer reports a warning for any class that is not final, abstract, or annotated with @api, provided the class has no children.

Defaults to false.

require_api_or_internal: bool

Require @api or @internal annotations on abstract classes, interfaces, and traits.

When enabled, the analyzer reports a warning for any abstract class, interface, or trait that is not annotated with either @api or @internal.

Defaults to false.

check_missing_type_hints: bool

Check for missing type hints on parameters, properties, and return types.

When enabled, the analyzer will report warnings for function parameters, class properties, and function return types that lack explicit type declarations. The analyzer uses its type system knowledge to avoid false positives - for instance, it won’t require a type hint on a property if adding one would conflict with a parent class or trait that has no type hint.

Defaults to false.

check_closure_missing_type_hints: bool

Check for missing type hints (both parameters and return types) in closures when check_missing_type_hints is enabled.

When true, closures (anonymous functions declared with function() {}) will be checked for missing type hints. When false, closures are ignored, which is useful because closures often rely on type inference.

Defaults to false.

check_arrow_function_missing_type_hints: bool

Check for missing type hints (both parameters and return types) in arrow functions when check_missing_type_hints is enabled.

When true, arrow functions (declared with fn() => ...) will be checked for missing type hints. When false, arrow functions are ignored, which is useful because arrow functions often rely on type inference and are typically short, making types obvious.

Defaults to false.

allow_implicit_pipe_callable_types: bool

Skip the missing-type-hint checks for closures and arrow functions used directly as the right-hand side of the pipe operator (|>).

When true, an inline pipe callable like $x |> fn($p) => strtoupper($p) will not warn about its parameter or return type being missing, even when check-closure-missing-type-hints or check-arrow-function-missing-type-hints is on. The pipe operand’s type is enough to derive the parameter type, so requiring a hint here is mostly noise.

Defaults to false.

register_super_globals: bool

Register superglobals (e.g., $_GET, $_POST, $_SERVER) in the analysis context.

If disabled, super globals won’t be available unless explicitly imported using the global keyword.

Defaults to true.

use_colors: bool

Enable colored output in terminal environments that support it. Defaults to true.

This setting is primarily used for enabling/disabling colored diffs in issue reports.

diff: bool

Internal use only.

Enables a diffing mode for incremental analysis, used by integrations like LSPs. This avoids re-analyzing unchanged code in the same session. Defaults to false.

trust_existence_checks: bool

Trust symbol existence checks to narrow types.

When enabled, conditional checks like method_exists(), property_exists(), function_exists(), and defined() will narrow the type within the conditional block, suppressing errors for symbols that are verified to exist at runtime.

When disabled, these checks are ignored and the analyzer requires explicit type hints, which is stricter but may produce more false positives for dynamic code.

Defaults to true.

class_initializers: Vec<ClassInitializer>

Method names treated as class initializers (like __construct).

Properties initialized in these methods count as “definitely initialized” just like in the constructor. This is useful for frameworks that use lifecycle methods like PHPUnit’s setUp() or framework boot() methods.

Entries can be either bare method names (applying to any class that has that method) or qualified as Fully\\Qualified\\Class::method to scope the rule to a specific class hierarchy.

Example: ["setUp", "boot", "PHPUnit\\Framework\\TestCase::setUpBeforeClass"]

Defaults to empty (no additional initializers).

check_property_initialization: bool

Enable property initialization checking (missing-constructor, uninitialized-property).

When false, disables both missing-constructor and uninitialized-property issues entirely. This is useful for projects that prefer to rely on runtime errors for property initialization.

Defaults to false.

check_use_statements: bool

Check for non-existent symbols in use statements.

When enabled, the analyzer will report use statements that import symbols (classes, interfaces, traits, enums, functions, or constants) that do not exist in the codebase.

Defaults to false.

check_experimental: bool

Check for usage of @experimental symbols from non-experimental contexts.

When enabled, the analyzer reports warnings when a symbol marked @experimental is used from a context that is not itself marked @experimental.

Defaults to false.

check_name_casing: bool

Check for incorrect casing when referencing classes, interfaces, traits, enums, and functions.

When enabled, the analyzer reports warnings when a symbol is referenced with different casing than its definition (e.g., new fooBar() when defined as FooBar). This helps prevent autoloading failures on case-sensitive file systems.

Defaults to false.

allow_side_effects_in_conditions: bool

Whether to allow calls to impure functions inside conditions.

When set to false, any call to a function not marked @pure or @mutation-free inside an if, while, for, ternary, or match condition is reported. This helps catch surprising evaluation-order bugs where a side effect in one part of a condition silently alters a variable used in another part.

Defaults to true (impure calls in conditions are allowed).

saturation_complexity_threshold: u16

Maximum number of clauses to process during CNF saturation.

Controls how many clauses the simplification algorithm will work with. If exceeded, saturation returns an empty result to avoid performance issues.

Defaults to 8192.

disjunction_complexity_threshold: u16

Maximum number of clauses per side in disjunction operations.

Controls the complexity limit for OR operations between clause sets. If either side exceeds this, the disjunction returns an empty result.

Defaults to 4096.

negation_complexity_threshold: u16

Maximum cumulative complexity during formula negation.

Controls how complex the negation of a formula can become. If exceeded, negation gives up to avoid exponential blowup.

Defaults to 4096.

consensus_limit_threshold: u16

Upper limit for consensus optimization during saturation.

Controls when the consensus rule is applied during saturation. Only applies when clause count is between 3 and this limit.

Defaults to 256.

formula_size_threshold: u16

Maximum logical formula size during conditional analysis.

Limits the size of generated formulas to prevent exponential blowup in deeply nested conditionals.

Defaults to 512.

string_combination_threshold: u16

Maximum number of literal strings to track before generalizing.

When combining types with many different literal string values, tracking each literal individually causes O(n) memory and O(n²) comparison time. Once the threshold is exceeded, we generalize to the base string type.

Defaults to 128.

integer_combination_threshold: u16

Maximum number of literal integers to track before generalizing.

When combining types with many different literal integer values, tracking each literal individually causes O(n) memory and O(n²) comparison time. Once the threshold is exceeded, we generalize to the base int type.

Defaults to 128.

array_combination_threshold: u16

Maximum number of array elements to track individually.

When building array types through repeated push operations ($arr[] = ...), this limits how many individual elements are tracked before generalizing to a simpler array type. This prevents memory explosion on files with thousands of array pushes.

Defaults to 128.

loop_assignment_depth_threshold: u8

Maximum depth of the loop assignment dependency graph that the fixed-point analyzer will explore when re-analysing loop bodies.

The analyzer uses fixed-point iteration to propagate widened types along loop-carried dependency chains. A chain of length N can require up to N extra passes for the type at the end of the chain to fully stabilise, and each pass re-analyses the entire loop body. On large, complex loops (think thousand-line procedural functions with deeply nested conditionals) the per-pass cost dominates file analysis time.

The default of 1 means each loop body is re-analysed at most once after the initial pass; enough to stabilise virtually all real-world code while keeping analysis cost bounded. Projects that require maximally precise narrowing of long loop-carried chains can raise this value (typically to 2 or 3) at the cost of significantly slower analysis on complex files.

Setting this to 0 disables fixed-point iteration entirely and analyses each loop body exactly once. This is the fastest option but may produce less precise types for variables that depend on themselves across iterations.

Defaults to 1.

Implementations

impl Settings

pub fn new(version: PHPVersion) -> Self

pub fn algebra_thresholds(&self) -> AlgebraThresholds

Returns the algebra thresholds derived from the settings.

pub fn combiner_options(&self) -> CombinerOptions

Returns the combiner options derived from the settings.

pub fn is_class_initializer_for( &self, meta: &ClassLikeMetadata, method_name: Word, ) -> bool

Returns true when method_name is a configured class initializer applicable to meta (either an unrestricted entry, or one whose class qualifier meta is a subclass/implementer of).

pub fn applicable_class_initializers<'cfg>( &'cfg self, meta: &'cfg ClassLikeMetadata, ) -> impl Iterator<Item = Word> + 'cfg

Iterator over initializer method names applicable to meta.

Trait Implementations

impl Clone for Settings

fn clone(&self) -> Settings

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Settings

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Settings

fn default() -> Self

Returns the “default value” for a type.

impl Eq for Settings

impl PartialEq for Settings

fn eq(&self, other: &Settings) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl StructuralPartialEq for Settings