Mago: The Oxidized PHP Toolchain

Mago (derived from Mago (Punic: 𐤌𐤂‬𐤍‬, MGN), a renowned Carthaginian figure) is a toolchain for PHP that aims to provide a set of tools to help developers write better code. Mago draws inspiration from the Rust programming language and its ecosystem, striving to bring similar convenience, reliability, and a great developer experience to the PHP world.

Note: This project was previously named “Fennec” before being rebranded due to a naming conflict.

Disclaimer

[!WARNING] Mago is in an early stage of development. Many features are not yet implemented, and existing functionality may change, break, or stop working without notice. While we are not actively promoting or advertising the project, we are working in public to share our progress with the community.

Roadmap

Core Functionality

• String Interning: crates/interner
• Lexer: crates/lexer crates/token
• AST: crates/ast
• Parser: crates/parser
• Source Management: crates/source
• AST Traversal / Walk: crates/traverser crates/walker
• Name Resolution: crates/names
• Code Fixer: crates/fixer
• Error Reporting: crates/reporting
• Semantic Analysis: crates/semantics
• Symbol Table: crates/symbol-table
• Linter: crates/linter
• Services: crates/service
• String Case Conversion: crates/casing
• Reflections: crates/reflection
• Reflector: crates/reflector, crates/scanner
• Type Inference: crates/typing
• Formatter: crates/formatter
• Static Analyzer
• Refactoring
• Code Generation
• Documentation Generation
• Docblock Parser crates/docblock

Tooling

• CLI Tool: crates/cli
• Web Assembly (WASM) Interface: crates/wasm
• Web Interface
• Language Server Protocol
• Editor Integration

Installation

Pre-compiled Binaries

You can find precompiled binaries for various platforms on our Releases page. Simply download the archive for your platform, extract it, and place the mago binary somewhere in your PATH.

Installation via Cargo

If you have Rust installed, you can install Mago using Cargo:

cargo install mago

Installation from source

To install Mago from source, you can clone the repository and build the project using Cargo:

git clone https://github.com/carthage-software/mago
cd mago
cargo install --path .

Usage

For a quick start, you can refer to the example configuration files provided:

• Simple configuration: examples/mago.toml
• Full configuration with all possible options: examples/mago-full.toml

You can try Mago by navigating to the examples directory and running the linter on the sample PHP files:

cd examples
mago lint
mago fmt

This will analyze the PHP files located in the examples/src/ directory and display any linting errors.

How You Can Help

Mago is a community-driven project, and we’d love for you to join us! Here are some ways you can contribute:

• Suggest Ideas: Have an idea for Mago? We’re open to suggestions that can make the toolchain even better!
• Help Write Documentation: Clear, user-friendly documentation is key to making Mago accessible to everyone. If you enjoy writing or organizing docs, we'd love your help.
• Contribute Code: Join us in building Mago! Please discuss any feature or bug fixes in the issues first to ensure we coordinate effectively.
• Sponsor the Project: If you’d like to support Mago financially, consider sponsoring @azjezz. Every contribution helps!
• Help with Art: Mago could use a logo! We’d appreciate the help of a skilled artist to create an original logo for Mago. (Please note that AI-generated art will not be accepted.)

Inspiration

Mago is inspired by several tools and projects that have significantly contributed to the development community:

• Clippy: A collection of lints to catch common mistakes and improve your Rust code.
• OXC: A JavaScript toolchain written in Rust.
• php-rust-tools/parser: A PHP parser written in Rust, which influenced our parsing approach.
• slackhq/hakana: A static analysis tool for HackLang written in Rust, by the creator of Psalm.

These tools have inspired us and helped shape Mago's design and functionality.

Acknowledgements

We would like to acknowledge the following PHP tools that have greatly helped hundreds of thousands of PHP developers in their journey, ourselves included:

• PHP CS Fixer: A tool to automatically fix PHP Coding Standards issues.
• Psalm: A static analysis tool for finding errors in PHP applications.
• PHPStan: PHP Static Analysis Tool.
• PHP_CodeSniffer: Detects violations of a defined set of coding standards.

While Mago is intended to be a comprehensive toolchain that may eventually replace some of these tools, we deeply appreciate their contributions and the foundation they have built for the PHP community.

License

Mago is licensed under either of

• MIT License (MIT) - see LICENSE-MIT file for details
• Apache License, Version 2.0 (Apache-2.0) - see LICENSE-APACHE file for details

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in Mago by you shall be dual licensed as above, without any additional terms or conditions.

Thank you for your interest in Mago. We look forward to sharing our progress and collaborating with the community as the project evolves.