Mago Laravel Package

Product Decisions This Supports

• Code Quality & Maintainability:

  • Unified Toolchain: Replace fragmented tooling (PHP-CS-Fixer, Psalm, PHPStan, PHP_CodeSniffer) with a single, high-performance solution, reducing cognitive load for developers and tooling overhead for the team.
  • Enforce Consistency: Standardize code style, linting, and static analysis across the entire codebase, improving onboarding and reducing merge conflicts.
  • Automated Fixes: Reduce manual refactoring effort by enabling --fix for common issues (e.g., formatting, minor syntax errors), accelerating PR reviews and CI/CD pipelines.

• Developer Experience (DX):

  • Faster Feedback Loops: Rust-based performance (sub-second linting for large codebases) enables real-time linting in IDEs (via plugins) or pre-commit hooks, improving productivity.
  • Semantic Safety: Catch PHP syntax/version mismatches early (e.g., unsupported features in target PHP version) before runtime errors occur, reducing debugging time.
  • Framework-Specific Rules: Leverage integrations for Laravel/Symfony/PHPUnit to enforce best practices tailored to the stack (e.g., Laravel’s dependency injection rules), reducing technical debt.

• Scalability & Cost:

  • Build vs. Buy: Avoid maintaining custom linting rules or integrating multiple tools (e.g., Psalm + PHPStan + PHP-CS-Fixer). Mago’s unified CLI and config (mago.toml) simplify adoption and maintenance.
  • CI/CD Optimization: Replace slow or resource-intensive tools (e.g., PHPStan’s static analysis) with Mago’s faster alternative, reducing CI runtime and costs.
  • Gradual Adoption: Start with semantic checks (--semantics) for quick wins, then layer in linting/rules incrementally (e.g., disable rules via enabled = false in mago.toml during migration).

• Roadmap Alignment:

  • PHP 8.4+ Readiness: Future-proof the codebase by catching unsupported features early (e.g., attribute hooks in PHP < 8.4) before they propagate.
  • AST-Based Refactoring: Enable advanced tooling (e.g., automated refactoring, migration scripts) by leveraging Mago’s AST visualization and parsing capabilities.
  • Open-Source Contribution: Sponsor or contribute to Mago to shape its roadmap (e.g., add missing Laravel-specific rules), ensuring long-term alignment with the team’s needs.

When to Consider This Package

Adopt Mago If:

• Tooling Fragmentation is Painful:

  • Your team uses 3+ tools (e.g., PHP-CS-Fixer, Psalm, PHPStan, PHP_CodeSniffer) with overlapping or conflicting rules, leading to:
    • Inconsistent configurations across projects.
    • Slow CI pipelines due to sequential tool execution.
    • Developer confusion about which tool to use for specific issues.
  • Example: A Laravel monorepo where PHPStan flags type errors, PHP-CS-Fixer enforces style, and PHP_CodeSniffer checks PSR-12, requiring manual coordination.

• Performance is a Bottleneck:

  • Current linting/static analysis tools (e.g., PHPStan, Psalm) take >5 seconds per run, blocking fast feedback loops in CI or local development.
  • Example: A high-traffic API where CI fails due to timeouts during static analysis.

• Framework-Specific Rules Are Critical:

  • Your stack (Laravel, Symfony, PHPUnit) has unique best practices that aren’t covered by generic tools (e.g., Laravel’s Illuminate\Container rules).
  • Example: Enforcing Symfony’s #[Route] annotations or Laravel’s use App\ namespace prefixes.

• Semantic Safety is a Priority:

  • Your team wants to catch PHP syntax/version issues (e.g., enum in PHP < 8.1) before runtime, but php -l is too limited.
  • Example: A legacy codebase migrating to PHP 8.2 where unsupported features slip into PRs.

• Automated Fixes Save Time:

  • Manual fixes for style issues (e.g., PSR-12) or minor syntax errors (e.g., missing return types) are a bottleneck in PR reviews.
  • Example: A team spending 20% of review time on nitpicks like trailing commas or docblock formatting.

• Gradual Migration is Needed:

  • You want to adopt Mago incrementally (e.g., start with semantic checks, then add linting) without disrupting existing workflows.

Look Elsewhere If:

• Your Stack is Non-PHP:

  • Mago is PHP-specific; for multi-language projects, consider alternatives like eslint (JS) or pylint (Python).

• You Need Deep Business Logic Analysis:

  • Mago’s static analysis is semantic but not as advanced as tools like Infection (mutation testing) or Pest (PHPUnit alternative) for testing logic.

• Your Team Resists Configuration Changes:

  • Mago requires migrating from .php-cs-fixer.dist.php/phpstan.neon to mago.toml. If stakeholders prefer minimal tooling changes, stick with incremental improvements to existing tools.

• You’re in a Highly Regulated Environment:

  • Mago’s MIT/Apache 2.0 license may not align with proprietary or government compliance requirements (though unlikely, verify legal team approval).

• Your Codebase is Tiny or Trivial:

  • For projects <10K LoC with no linting needs, Mago’s overhead may not justify adoption.

How to Pitch It (Stakeholders)

For Executives (Business/Technical Leaders)

Problem: "Our code quality tools are fragmented, slow, and inconsistent. Developers spend time fixing style issues or debugging syntax errors that could be caught automatically. This slows down releases and increases technical debt."

Solution: "Mago is a single, ultra-fast PHP toolchain (written in Rust) that replaces 5+ tools (PHP-CS-Fixer, Psalm, PHPStan, etc.) with one CLI. It:

• Speeds up CI by 80% (sub-second linting for large codebases).
• Reduces PR review time with automated fixes for style/syntax issues.
• Catches PHP version/syntax errors early, preventing runtime bugs.
• Enforces framework-specific rules (e.g., Laravel/Symfony best practices).
• Lowers maintenance costs by eliminating tooling sprawl."*

ROI:

• Dev Productivity: Save 1–2 hours/week per developer on manual fixes and reviews.
• Release Velocity: Faster CI pipelines enable more frequent, reliable deployments.
• Quality: Fewer production bugs from caught syntax/version issues.
• Cost: Eliminate need for multiple paid licenses (e.g., Psalm Pro) or custom tooling.

Risk Mitigation:

• "We’ll pilot Mago on one repo first, with a fallback to current tools if needed. The config migration is straightforward, and we can disable rules incrementally."

For Engineering Teams (Devs/Architects)

Problem: "Running php-cs-fixer, phpstan, and psalm in CI takes 10 minutes. Local linting is slow. And we still get PRs with PHP version mismatches or style violations."

Solution: "Mago is a drop-in replacement that:

• Runs in <1s for most projects (Rust-based, parallelized).
• Fixes 80% of style issues automatically with --fix.
• Catches PHP syntax/version errors (e.g., enum in PHP 8.0) before runtime.
• Supports framework rules (e.g., Laravel’s use App\ namespace enforcement).
• Uses a single config file (mago.toml) instead of 3+ configs."*

Key Features to Highlight:

Migration Path:

1. Week 1: Add Mago to CI for semantic checks (mago lint --semantics).
2. Week 2: Enable linting with --fix for style issues.
3. Week 3: Migrate framework-specific rules (e.g., Laravel integrations).
4. Week 4: Deprecate old tools (PHP-CS-Fixer, Psalm, etc.).

**Try