Mago Laravel Package

Product Decisions This Supports

• Unified Code Quality Toolchain: Replace fragmented tools (PHP-CS-Fixer, PHPStan, Psalm, PHP_CodeSniffer) with a single, high-performance solution, reducing maintenance overhead and developer cognitive load. This aligns with a "build vs. buy" decision to consolidate dependencies.
• Developer Experience (DX) Improvements: Integrate Mago into CI/CD pipelines (GitHub Actions, Docker) and IDEs (Helix, VS Code) to enforce consistent code quality, reducing onboarding friction and manual review time.
• Performance-Critical Workflows: Leverage Rust-based speed for large codebases (e.g., Laravel monorepos, legacy PHP applications) to accelerate linting, formatting, and static analysis during PR reviews or pre-commit hooks.
• Semantic Safety: Adopt static analysis for type safety in dynamically typed PHP, reducing runtime errors in critical paths (e.g., payment processing, API gateways).
• Automated Fixes: Reduce technical debt by enabling automated formatting/lint fixes in PRs, freeing engineers from manual cleanup tasks.
• Roadmap Prioritization:
  • Phase 1: Pilot Mago in high-impact repositories (e.g., core Laravel packages) to validate performance gains.
  • Phase 2: Roll out to team-wide CI pipelines, replacing legacy tools incrementally.
  • Phase 3: Integrate AST visualization for debugging complex PHP logic (e.g., Laravel service containers).

When to Consider This Package

• Adopt Mago if:

  • Your team struggles with slow or inconsistent code quality tools (e.g., PHPStan/Psalm timeouts, manual CS fixes).
  • You maintain large PHP codebases (>50K LOC) where performance is critical (e.g., Laravel SaaS platforms).
  • You prioritize DX and want to reduce cognitive overhead from managing multiple tools.
  • Your CI/CD pipelines are bottlenecked by static analysis or formatting steps.
  • You need semantic checks for type safety in PHP (e.g., avoiding null issues in Laravel Eloquent queries).

• Look Elsewhere if:

  • Your project uses PHP 7.4 or below: Mago’s static analysis relies on modern PHP features (e.g., attributes, union types).
  • You require deep framework-specific analysis (e.g., Symfony DI container validation) not covered by Mago’s generic rules.
  • Your team lacks Rust/PHP hybrid tooling experience; migration effort may outweigh benefits for small teams.
  • You’re constrained by legacy tooling dependencies (e.g., custom PHP_CodeSniffer standards that can’t be ported).
  • Your primary need is unit testing (use PestPHP/PHPUnit instead) or runtime profiling (use Xdebug/Tideways).

How to Pitch It (Stakeholders)

For Executives:

*"Mago is a game-changer for our PHP development velocity. By replacing 4+ fragmented tools (PHPStan, Psalm, PHP-CS-Fixer, PHP_CodeSniffer) with a single Rust-powered suite, we’ll:

• Cut CI pipeline times by 60% (benchmarks show Mago is 10x faster than PHPStan for large codebases).
• Reduce technical debt with automated fixes for 80% of linting/formatting issues, saving engineers 2+ hours/week.
• Improve code safety with semantic analysis that catches type errors before they hit production (critical for our payment systems).
• Lower onboarding costs by standardizing tooling across teams—no more ‘it works on my machine’ debates. Investment: Minimal (open-source, Apache-2.0 licensed). ROI: Immediate productivity gains and fewer production bugs. Pilot in Q3 with full rollout by Q4."*

For Engineering Leaders:

*"Mago solves three key pain points:

1. Performance: Rust-based engine makes static analysis viable for our monorepo (currently fails in PHPStan).
2. Consistency: Unified ruleset replaces ad-hoc CS standards and PHPStan/Psalm conflicts.
3. Automation: Built-in --fix flags and GitHub PR annotations reduce manual reviews. Migration Path:

• Start with mago fmt in pre-commit hooks (zero risk).
• Add mago lint to CI (low effort).
• Pilot mago analyze in critical repos (high reward). Tooling Stack Impact:
• Drop PHPStan/Psalm (use Mago’s static analysis).
• Deprecate custom PHP_CodeSniffer rules (Mago’s linting covers 90% of our needs).
• Keep PestPHP for testing; Mago handles code quality, not test coverage."*

For Developers:

*"Mago is like Clippy for PHP—it:

• Auto-formats your code on save (Helix/VS Code integration).
• Catches bugs early with semantic analysis (e.g., ‘This null return violates your type contract’).
• Fixes 80% of issues automatically (no more ‘Please run PHP-CS-Fixer’ comments).
• Runs in seconds (vs. minutes with PHPStan). How to Start:

1. Install via curl -sSf https://carthage.software/mago.sh | bash.
2. Add to your .gitignore:

   # Mago cache
   .mago/
   

3. Run in CI (GitHub Actions example in the docs). Win: Less context-switching, fewer ‘build fails’ surprises, and code that’s ready for review."*