Mago Laravel Package

Technical Evaluation

Architecture Fit

• Strengths:

  • Performance: Rust-based engine ensures near-instant linting/formatting, critical for CI/CD pipelines and large Laravel monorepos.
  • Unified Toolchain: Combines linting, static analysis, and formatting into a single CLI, reducing toolchain fragmentation (vs. PHP-CS-Fixer + Psalm + PHPStan).
  • Semantic Awareness: Deep PHP AST parsing enables advanced checks (e.g., type safety, framework-specific rules) without requiring separate analyzers.
  • Framework Integrations: Native support for Laravel (via Symfony integration) reduces false positives/negatives in framework-specific code (e.g., dependency injection, route definitions).
  • Automated Fixes: Built-in --fix with dry-run support aligns with Laravel’s emphasis on developer productivity.

• Challenges:

  • Rust Dependency: Requires Rust toolchain installation (adds complexity to dev environments, especially for non-PHP teams).
  • Learning Curve: Configuration (mago.toml) and rule granularity may overwhelm teams accustomed to simpler tools like PHP-CS-Fixer.
  • Legacy Code: Rust’s strict parsing may flag valid legacy PHP (e.g., dynamic properties, pre-8.0 constructs) as errors, requiring rule exclusions.

Integration Feasibility

• Laravel Stack Fit:
  • Core PHP: Replaces/augments PHP-CS-Fixer, Psalm, and PHPStan with a single tool.
  • Framework-Specific: Laravel integrations (e.g., route validation, Eloquent checks) reduce manual rule tuning.
  • CI/CD: Sub-second execution enables pre-commit hooks and GitHub Actions without slowing pipelines.
• Compatibility:
  • PHP Versions: Supports PHP 8.1+ (Laravel’s minimum). Backward compatibility for older PHP may require rule exclusions.
  • Tooling: Works alongside Laravel Mix/Vite, Forge, and Envoyer (CLI-based).
  • IDE: Integrates with PHPStorm/VSCode via language servers (e.g., Intelephense).

Technical Risk

• High:
  • Adoption Friction: Teams may resist replacing multiple tools with one new Rust-based tool.
  • Rule Customization: Laravel-specific rules may need community contributions or forks (e.g., custom validation logic for Laravel’s HasFactory).
  • Debugging: Rust-based errors (e.g., AST parsing failures) may be harder to debug than PHP-native tools.
• Mitigation:
  • Phased Rollout: Start with linting/formatting in CI, then add static analysis.
  • Baseline Mode: Use baseline to ignore existing violations during migration.
  • Documentation: Create internal runbooks for common Laravel-specific rules (e.g., no-undefined-route).

Key Questions

1. Rule Coverage: Does Mago’s Laravel integration cover critical pain points (e.g., route caching, service container binding) better than Psalm/PHPStan?
2. Performance: How does Mago scale for Laravel apps with 10K+ files (e.g., SaaS platforms)?
3. Maintenance: Who will maintain Laravel-specific rules if the project stagnates?
4. Toolchain Lock-in: Can Mago’s configuration be version-controlled alongside Laravel’s codebase (e.g., mago.toml in .git)?
5. Legacy Support: How does Mago handle Laravel apps using deprecated features (e.g., Route::controller)?

Integration Approach

Stack Fit

• Primary Use Cases:
  • CI/CD: Replace php-cs-fixer, phpstan, and psalm with a single mago lint command.
  • Local Dev: Add to composer.json scripts (e.g., pre-commit) and IDE hooks.
  • Onboarding: Use --semantics for quick PHP syntax validation during developer setup.
• Laravel-Specific:
  • Leverage integrations = ["symfony"] for Laravel’s Symfony-based components (e.g., routing, HTTP kernel).
  • Custom rules for Laravel idioms (e.g., use App\Models\* imports, HasFactory trait usage).

Migration Path

1. Phase 1: Linting/Formatting

   • Replace PHP-CS-Fixer with mago lint --fix.
   • Configure mago.toml to mirror existing .php-cs-fixer.dist.php rules.
   • Risk: Rule name differences (e.g., no_unused_imports vs. unused-import) require mapping.

2. Phase 2: Static Analysis

   • Replace Psalm/PHPStan with mago lint --semantics for type safety.
   • Use baseline to ignore existing type errors during transition.
   • Risk: False positives in dynamic Laravel code (e.g., app() helper).

3. Phase 3: Framework Integrations

   • Enable integrations = ["symfony", "laravel"] (if available) for framework-specific checks.
   • Contribute/customize rules for Laravel’s unique patterns (e.g., Route::resource validation).

Compatibility

• Tooling:
  • Composer: Install via composer require carthage-software/mago.
  • Git Hooks: Use mago lint in pre-commit (faster than PHPStan).
  • CI: Replace parallel php-cs-fixer, phpstan, and psalm jobs with a single mago lint job.
• IDE:
  • Integrate with Intelephense or PHPStorm’s PHP Intelephense for real-time linting.
  • Configure mago.toml rules to match IDE expectations (e.g., level = "warning" for IDE-friendly errors).

Sequencing

Operational Impact

Maintenance

• Pros:
  • Single Configuration: mago.toml replaces .php-cs-fixer.dist.php, phpstan.neon, and psalm.xml.
  • Automated Updates: Rust-based performance reduces maintenance overhead (e.g., no need to optimize PHPStan’s memory usage).
  • Community: Active development (3.3K stars, recent releases) suggests long-term viability.
• Cons:
  • Rust Dependency: Requires periodic Rust toolchain updates (though binary releases mitigate this).
  • Rule Drift: Laravel-specific rules may diverge from upstream Mago (need for forks or patches).
  • Debugging: Complex AST errors may require Rust knowledge to resolve.

Support

• Developer Experience:
  • Onboarding: --semantics provides a low-friction entry point for new devs.
  • Feedback: Clear error messages with --explain for rule-specific help.
  • Fixes: --fix with --dry-run reduces fear of breaking changes.
• Team Skills:
  • Upskill: Rust-based tooling may require team training (though CLI usage is PHP-agnostic).
  • Custom Rules: PHP devs can contribute rules via Rust (steep learning curve) or TOML config.
• SLA Impact:
  • Faster Feedback: Sub-second linting reduces CI noise and local dev frustration.
  • Blockers: Static analysis may uncover critical issues earlier (e.g., type errors in Eloquent models).

Scaling

• Performance:
  • Large Codebases: Rust engine handles 10K+ files in <1s (benchmarked in docs).
  • Parallelization: Built-in parallel scanning (vs. PHPStan’s sequential analysis).
  • Memory: Lower memory footprint than PHPStan/Psalm (critical for CI).
• Resource Limits:
  • CI: No risk of OOM kills (unlike PHPStan on large apps).
  • Local Dev: Lightweight enough for laptops (tested on CodSpeed).

Failure Modes