mago

Mago's linter includes 176 rules organized into 9 categories to improve code quality, security, and maintainability. Rules are categorized as follows:

• Clarity: Makes intent explicit and reduces reader effort.
• Best practices: Encourages idiomatic PHP patterns.
• Consistency: Ensures stylistic uniformity.
• Deprecation: Flags deprecated PHP features and APIs.
• Maintainability: Surfaces code complexity and fragility.
• Redundancy: Identifies dead code and unused constructs.
• Security: Flags vulnerabilities and unsafe patterns.
• Safety: Catches patterns that may cause runtime errors.
• Correctness: Detects bugs and logic errors.

Mago is a single binary that bundles four distinct tools. These tools share a common configuration, parser, and runtime, allowing you to use any combination of them efficiently. The bundled tools are:

• Formatter: A deterministic code formatter.
• Linter: A rule-based tool for correctness, consistency, and security.
• Analyzer: A static analysis engine for type errors and logic bugs.
• Architectural guard: A tool for enforcing dependency rules and structural conventions.

mago guard is a tool used to enforce architectural boundaries and structural conventions within a PHP project. It functions as a single binary powered by Mago's parser and serves as an alternative to tools like deptrac and arkitect.

The tool is divided into two primary functional areas:

1. Perimeter guard: Validates dependency edges between different layers of an application (e.g., ensuring the Domain layer does not depend on infrastructure).
2. Structural guard: Enforces conventions on individual symbols, such as naming patterns, modifiers (e.g., final), supertypes, attributes, and namespace structures.

mago-wasm is a WebAssembly (WASM) crate that provides high-level Mago toolchain functionality specifically for browser environments. It is designed for use in projects like the Mago Playground where running Mago directly in a web browser is necessary.

Note: If you are building applications outside of a browser context, use the dedicated Mago crates instead of mago-wasm.

Mago is a high-performance PHP toolchain written in Rust that provides several key capabilities:

• Linting: Identify codebase issues using customizable rules.
• Static Analysis: Perform deep analysis to catch type errors and bugs.
• Automated Fixes: Automatically apply fixes for many identified lint issues.
• Formatting: Automatically format code to adhere to best practices and style guides.
• Semantic Checks: Ensure code correctness through robust semantic analysis.
• AST Visualization: Explore code structure via Abstract Syntax Tree (AST) parsing.

Mago provides a unified toolchain for PHP development without requiring a PHP runtime, Composer, or Java. It includes the following core tools:

• Formatter: Produces deterministic output following PER-CS by default.
• Linter: Provides a curated catalogue of rules across nine categories, many of which support automatic fixes.
• Static Analyzer: Catches type errors and logic bugs before runtime; supports Psalm and PHPStan annotations.
• Architectural Guard: Enforces dependency rules and structural conventions.

The Mago Formatter is a deterministic formatter for PHP designed to enforce a consistent coding style across projects. It uses a 'parse-and-reprint' approach: it parses source code into an Abstract Syntax Tree (AST), discards the original formatting, and reprints the AST from scratch based on a fixed set of rules. This ensures that the output is identical for a given AST regardless of the input style, while strictly preserving the program's runtime behavior.

Key features include:

• Opinionated Consistency: Enforces a single style across the project.
• Style Presets: Uses PER-CS by default, with optional presets for PSR-12, Laravel, and Drupal.
• Safety: Constrained to changes that cannot alter program behavior.
• Performance: Built with a Rust core and an arena-backed pipeline for high-speed formatting.

Mago provides two distinct tools for code quality:

• Linter: Focuses on the shape of your code. It enforces stylistic conventions, flags redundant constructs, and suggests modern syntax without needing to understand runtime behavior.
• Analyzer: Focuses on the semantics of your code. It builds a model of your entire codebase to understand types, properties, and return values, allowing it to find logical errors like calling non-existent methods on a specific type.

Mago's primary focus is providing a complete QA and development utility for PHP.

Current focus for 1.0.0:

• Formatter
• Linter
• Analyzer

Planned future tools:

• PHP version manager
• PHP extension installer
• Migration helper (for upgrading PHP versions, frameworks, or libraries)

Mago is designed to prioritize execution speed and developer time over machine resources. This results in specific memory usage patterns:

• Static Analysis: Typically uses significantly less memory than alternatives (e.g., approximately 3.5x less than Psalm).
• Linting and Formatting: May use more memory than single-threaded PHP tools.

This behavior is due to the use of per-thread arena allocators. Mago reserves large chunks of memory upfront to enable heavy parallelism and near-zero cost allocations, which can lead to a higher peak memory footprint in exchange for much faster execution.