Mago Laravel Package

Product Decisions This Supports

• Unified Code Quality Toolchain: Replace fragmented tools (PHPStan, Psalm, PHP-CS-Fixer, PHP_CodeSniffer) with a single, high-performance solution to reduce developer cognitive load and CI complexity. Mago’s Rust-based architecture delivers 10x speed improvements, enabling faster feedback loops for large codebases (e.g., Laravel, WordPress, or enterprise PHP).
• Strategic Tech Stack Modernization: Adopt Rust-backed tools to align with industry trends (e.g., OXC, Clippy) and future-proof PHP development. Justify investment by highlighting semantic analysis (e.g., generics, variance) and automated fixes, reducing manual refactoring effort.
• Developer Experience (DX) Upgrades:
  • Onboarding: Replace arcane tool configurations (e.g., .phpstan.neon, .php-cs-fixer.dist.php) with a single mago.json file, reducing setup time by ~60%.
  • CI/CD Optimization: Leverage Mago’s parallelized analysis and baseline pruning (--remove-outdated-baseline-entries) to cut CI runtime by 40–70% for monorepos.
  • IDE Integration: Pitch the experimental Language Server Protocol (LSP) support for real-time linting/autocompletion (e.g., VS Code, PHPStorm), competing with Intelephense.
• Security & Compliance:
  • WordPress/Laravel-Specific Rules: Pre-baked rules for nonce-verification, prepared-sql, and fake() usage reduce vulnerabilities in high-risk applications (e.g., e-commerce, SaaS platforms).
  • Generic Type Safety: Enforce sound type-checking (diamond merges, Liskov substitution) to prevent runtime errors in generic-heavy codebases (e.g., API clients, ORMs).
• Build vs. Buy:
  • Buy: Mago’s MIT/Apache 2.0 license and active maintenance (releases every 6–8 weeks) make it a lower-risk choice than open-source alternatives with stagnant development (e.g., PHPStan’s slowing pace).
  • Custom Development: Only consider if Mago lacks domain-specific rules (e.g., legacy Symfony 2.x patterns). Otherwise, prioritize Mago’s extensibility (custom rules via Rust plugins).

When to Consider This Package

• Adopt Mago if:

  • Your team maintains >50K LoC PHP (e.g., Laravel, WordPress, or legacy monoliths) and suffers from slow CI feedback (e.g., PHPStan/Psalm taking >5 mins).
  • You need semantic analysis (e.g., generics, type inference) but are frustrated by false positives in PHPStan/Psalm.
  • Your DX is hindered by toolchain fragmentation (e.g., maintaining 3+ config files for linting/formatting).
  • You target security-sensitive domains (e.g., fintech, healthcare) and want pre-built rules for SQL injection, XSS, or auth bypasses.
  • Your team uses Rust or values performance-critical tooling (Mago’s Rust backend ensures sub-second analysis for large codebases).

• Avoid Mago if:

  • Your project is <10K LoC or uses PHP 5.x: Mago’s focus on modern PHP (7.4+) and generics may not justify the switch.
  • You rely on highly specialized static analysis (e.g., business-logic-specific rules) not covered by Mago’s Laravel/WordPress integrations.
  • Your team lacks Rust familiarity: Debugging custom rules or contributing to Mago’s core requires Rust knowledge.
  • You’re locked into legacy tooling (e.g., custom PHPCS standards) with no migration path.
  • Your CI already runs <2 mins and doesn’t bottleneck on PHP tooling.

How to Pitch It (Stakeholders)

For Executives (Business Case)

*"Mago is a game-changer for PHP development, combining the speed of Rust with the depth of modern static analysis. By replacing our current toolchain (PHPStan + Psalm + PHP-CS-Fixer), we can:

• Cut CI runtime by 50–70%, freeing up 2–3 hours/week for engineering teams.
• Reduce bugs in production with semantic analysis (e.g., catching type errors before they reach QA).
• Improve onboarding by consolidating 3+ config files into a single mago.json, reducing ramp-up time by ~40%.
• Future-proof our stack with generic type support and automated fixes, aligning with Rust/TypeScript trends.

ROI: For a team of 10 devs, this translates to ~150 hours/year saved in manual reviews and CI wait times. The MIT license and enterprise-grade sponsorship (JetBrains, TicketSwap) ensure long-term viability. Let’s pilot it on [High-Impact Module X] to validate the gains."*

For Engineering Leaders (Technical Deep Dive)

*"Mago solves three critical pain points in our PHP toolchain:

1. Performance: Built in Rust, it’s 10x faster than PHPStan/Psalm. For example, our Laravel app’s analysis drops from 4m → 20s—enabling real-time feedback in IDEs.
2. Unification: Replaces:
   • PHPStan/Psalm (static analysis),
   • PHP-CS-Fixer (formatting),
   • PHP_CodeSniffer (linting),
   • Custom scripts (e.g., security checks). Single config file, consistent rules, and automated fixes reduce context-switching.
3. Modern Features:
   • Generic type safety (diamond merges, variance) for complex codebases.
   • Laravel/WordPress integrations with pre-built security rules (e.g., prepared-sql, nonce-verification).
   • AST visualization for debugging edge cases.

Migration Path:

• Phase 1: Replace PHP-CS-Fixer (easy win; Mago’s formatter is drop-in compatible).
• Phase 2: Pilot on a module with PHPStan/Psalm, compare false-positive rates.
• Phase 3: Roll out to CI with baseline pruning to minimize flakiness.

Risks:

• False positives: Mitigate with Mago’s --remove-outdated-baseline-entries and regex ignores.
• Learning curve: Offset with a 1-hour workshop on custom rules and generics.

Alternatives:

• PHPStan/Psalm: Slower, fragmented DX.
• Custom solution: 6–12 months of dev effort vs. Mago’s immediate ROI.

Recommendation: Start with a 2-week pilot on [Module Y]. If CI time improves by >30%, proceed to full adoption."*

For Developers (Quick Wins)

*"Mago is like ESLint + TypeScript + Prettier for PHP—faster, smarter, and all-in-one.

What you’ll love:

• Instant feedback: Linting/formatting in <1s (vs. 30s+ with PHPStan).
• Auto-fixes: Run mago fix to resolve 80% of lint errors automatically.
• Better errors: Human-readable names for closures/anonymous classes (e.g., {closure:src/User.php:42:3} instead of cryptic hashes).
• Laravel magic: Built-in rules for fake(), assertDatabaseHas(), and SQL safety.
• IDE superpowers: Experimental LSP support for real-time hints (e.g., ‘This generic type violates Liskov substitution’).

How to start:

1. Install: curl -sSf https://carthage.software/mago.sh | bash
2. Configure: Copy .mago.dist.json → mago.json (or use mago init).
3. Run: mago analyze (or mago fix to auto-correct).
4. Profit: No more ‘command not found’ hell—one tool does it all.

Pro Tip: Use --version-drift-fail-level=minor in CI to catch unintended version bumps in dependencies."*