Mago Laravel Package

Technical Evaluation

Architecture Fit

Mago’s Rust-based toolchain is a highly performant alternative to PHP-native tools (e.g., PHPStan, Psalm, PHP-CS-Fixer) and aligns well with Laravel’s need for speed, scalability, and maintainability. Key strengths for Laravel:

• Unified toolchain: Combines linting, static analysis, formatting, and semantic checks in one package, reducing dependency sprawl.
• Laravel-specific rules: Built-in support for Laravel patterns (e.g., test assertions, query validation, fake() usage) reduces custom rule overhead.
• Rust performance: Near-instant feedback loops for large codebases (critical for CI/CD pipelines).
• AST-based analysis: Enables deep semantic checks (e.g., generic type inference, variance enforcement) that PHP-native tools struggle with.

Potential misfit:

• Learning curve: Rust-based tooling may require upskilling teams unfamiliar with Mago’s CLI/configuration.
• Legacy PHP compatibility: Some edge cases (e.g., older PHP versions, niche frameworks) may need explicit configuration.

Integration Feasibility

• Composer integration: Installable via composer require carthage-software/mago, with minimal setup (e.g., mago init).
• CI/CD readiness: Supports GitHub Actions, GitLab CI, and other pipelines via CLI flags (e.g., --fail-level=error).
• IDE/LSP support: Experimental Language Server Protocol (LSP) integration for real-time feedback in VS Code/PhpStorm.
• Migration path: Can coexist with existing tools (e.g., run alongside PHPStan for gradual adoption).

Blockers:

• Baseline management: Mago’s baseline system (for ignoring false positives) requires upfront configuration.
• Custom rules: Laravel-specific rules are included, but domain-specific rules may need extension.

Technical Risk

Key questions for the team:

1. Adoption velocity: How quickly can the team migrate from PHPStan/PHP-CS-Fixer to Mago?
2. Custom rule needs: Are there Laravel-specific patterns not covered by Mago’s built-in rules?
3. CI/CD impact: How will Mago’s exit codes (--fail-level) integrate with existing pipelines?
4. Team expertise: Is there Rust/PHP tooling experience to debug edge cases?
5. Baseline maintenance: Who will curate and update baseline files for new false positives?

Integration Approach

Stack Fit

Mago is optimized for modern PHP/Laravel stacks:

• Performance: Rust-based engine outperforms PHP-native tools (e.g., 10x faster than PHPStan for large codebases).
• Language Server: Experimental LSP support enables IDE integration (e.g., real-time linting in VS Code).
• Composer ecosystem: Seamless integration with composer.json and Laravel’s dependency management.
• CI/CD: Lightweight binary reduces pipeline overhead (critical for monorepos).

Compatibility:

• PHP 8.1+: Laravel’s minimum version (8.0+) is supported with minor config tweaks.
• Frameworks: Built-in Laravel rules; WordPress rules suggest broad PHP ecosystem support.
• Tooling: Replaces PHPStan, Psalm, PHP-CS-Fixer, and PHP_CodeSniffer in one tool.

Migration Path

Phase 1: Pilot (2–4 weeks)

• Scope: Start with a single Laravel module (e.g., auth or api).
• Setup:

  composer require carthage-software/mago --dev
  npx mago init
  

• Configuration:
  • Extend mago.php with Laravel-specific rules:

    return [
        'rules' => [
            'laravel.test-assertions' => true,
            'laravel.query-validation' => true,
        ],
    ];
    

• CI Integration:

  # GitHub Actions example
  - name: Run Mago
    run: npx mago analyze --fail-level=error
  

Phase 2: Gradual Rollout (4–8 weeks)

• Parallel run: Execute Mago alongside PHPStan to compare results.
• Baseline tuning: Use mago analyze --generate-baseline to capture false positives.
• Team training: Document common rules (e.g., no-redundant-variable, prefer-fake-helper).

Phase 3: Full Adoption

• Deprecate legacy tools: Remove PHPStan/PHP-CS-Fixer from composer.json.
• Enforce formatting: Add mago format to pre-commit hooks.
• Optimize CI: Cache Mago’s Rust binary to reduce pipeline time.

Compatibility

Sequencing:

1. Linting: Replace PHP_CodeSniffer/Psalm with Mago’s mago lint.
2. Static Analysis: Replace PHPStan with Mago’s mago analyze.
3. Formatting: Replace PHP-CS-Fixer with mago format.
4. Language Server: Enable LSP for IDE integration (if stable).

Sequencing Dependencies

• Prerequisite: PHP 8.1+ (Laravel 8.0+ compatible).
• Order:
  1. Install Mago via Composer.
  2. Configure mago.php with Laravel rules.
  3. Run in CI with --fail-level=warning (gradual enforcement).
  4. Migrate baselines from PHPStan/Psalm.
  5. Deprecate legacy tools.

Operational Impact

Maintenance

• Pros:
  • Single tool: Reduces maintenance overhead (no syncing between PHPStan/PHP-CS-Fixer).
  • Rust stability: Fewer runtime issues than PHP-native tools.
  • Active development: Frequent releases (e.g., 1.28.0, 1.29.0) with Laravel-specific fixes.
• Cons:
  • Baseline drift: Requires periodic updates as code evolves.
  • Custom rules: May need maintenance for Laravel-specific edge cases.

Effort Estimate:

Support

• Documentation: Comprehensive official docs and GitHub README.
• Community:
  • Discord channel for real-time help.
  • GitHub issues for bug reports/feature requests.
• Enterprise Support: Sponsorship options (e.g., JetBrains, TicketSwap) for SLAs.

Common Support Needs:

1. False positives: Use mago analyze --generate-baseline to suppress known issues.
2. Rule customization: Extend mago.php or create custom rules via Rust (advanced).
3. Performance tuning: Adjust --parallel or --memory-limit for large codebases.

Scaling

• Performance:
  • Large codebases: Rust engine handles 50K+ LOC in <5s (benchmarked).
  • Parallelism: Supports --parallel=N for multi-core execution.
  • Memory: Configurable limits (--memory-limit=2G).
• Distributed Teams:
  • Baseline sharing: Store mago.baseline in repo to ensure consistency.
  • CI caching: Cache Mago’s Rust binary