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.

Installation

One-Line Installation (Recommended)

To quickly install the latest release of Mago for macOS or Linux, use the following command:

Using curl:

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

Using wget:

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

Custom Installation Directory

To specify a custom directory for the binary, use the --install-dir option:

curl --proto '=https' --tlsv1.2 -sSf https://carthage.software/mago.sh | bash -s -- --install-dir="/.bin"

If the directory is not in your PATH, the script will provide instructions to add it.

Installing with sudo

If you need to install Mago system-wide, you can use sudo with the installation command:

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

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 .

PHP Version Compatibility

Currently, Mago is built around PHP 8.3 and also supports PHP 8.4. While the linter and formatter may work with earlier versions of PHP, we cannot guarantee compatibility. They might suggest fixes or write code that is only compatible with PHP 8.3 and later.

At this stage, there is no option to select a PHP version target, which means Mago operates under the assumption of modern PHP versions. In the future, we plan to introduce support for selecting a PHP version target. Once implemented, this feature should enable better compatibility with earlier PHP versions, potentially down to PHP 8.0 or even earlier.

If you're working with PHP versions prior to 8.3, please proceed with caution and review suggested fixes or formatted code to ensure compatibility with your version.

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.)

Join the Mago Community

Got questions, feedback, or ideas? Join the Mago community on Discord to connect with other developers and stay up-to-date.

Join Here

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.