carthage-software/mago

Mago is a toolchain for PHP that aims to provide a set of tools to help developers write better code.

1.0.0-alpha.3 2025-08-07 00:23 UTC

Requires

• php: ~8.1 || ~8.2 || ~8.3 || ~8.4
• composer-plugin-api: ^2.6

Requires (Dev)

• composer/composer: ^2.8

MIT OR Apache-2.0

• Saif Eddin Gmati

• dev

README

An extremely fast PHP linter, formatter, and static analyzer, written in Rust.

Mago is a comprehensive toolchain for PHP that helps developers write better code. Inspired by the Rust ecosystem, Mago brings speed, reliability, and an exceptional developer experience to PHP projects of all sizes.

Table of Contents

• Installation
• Getting Started
• Features
• Contributing
• Inspiration & Acknowledgements
• License

How to Install

Shell (Linux, macOS)

# with curl
curl --proto '=https' --tlsv1.2 -sSf https://carthage.software/mago.sh | bash

# with wget
wget -qO- https://carthage.software/mago.sh | bash

Package Managers

Homebrew (macOS)

brew install mago

Composer (PHP Project)

composer require --dev carthage-software/mago

Cargo (Rust Toolchain)

cargo install mago

Manual Download

You can download pre-compiled binaries for your system from the GitHub Releases page.

Getting Started

Once installed, you can start using Mago immediately.

1. Lint your project:

mago lint src/

1. Format your code:

mago format src/

For detailed usage, configuration options, and available rules, please visit the Mago Documentation.

Features

• ⚡️ Extremely Fast: Built in Rust for maximum performance.
• 🔍 Lint: Identify issues in your codebase with customizable rules.
• 🔬 Static Analysis: Perform deep analysis of your codebase to catch potential type errors and bugs.
• 🛠️ Automated Fixes: Apply fixes for many lint issues automatically.
• 📜 Formatting: Automatically format your code to adhere to best practices and style guides.
• 🧠 Semantic Checks: Ensure code correctness with robust semantic analysis.
• 🌳 AST Visualization: Explore your code’s structure with Abstract Syntax Tree (AST) parsing.

Contributing

Mago is a community-driven project, and we welcome contributions! Whether you're reporting bugs, suggesting features, writing documentation, or submitting code, your help is valued.

• See our Contributing Guide to get started.
• Join the discussion on Discord.

Inspiration & Acknowledgements

Mago stands on the shoulders of giants. Our design and functionality are heavily inspired by pioneering tools in both the Rust and PHP ecosystems.

Inspirations:

• Clippy: For its comprehensive linting approach.
• OXC: A major inspiration for building a high-performancetoolchain in Rust.
• Hakana: For its deep static analysis capabilities.

Acknowledgements:

We deeply respect the foundational work of tools like PHP-CS-Fixer, Psalm, PHPStan, and PHP_CodeSniffer. While Mago aims to offer a unified and faster alternative, these tools paved the way for modern PHP development.

License

Mago is dual-licensed under your choice of the following:

• MIT License (LICENSE-MIT)
• Apache License, Version 2.0 (LICENSE-APACHE)