Mago Laravel Package

Getting Started

Minimal Setup

1. Installation:

   curl --proto '=https' --tlsv1.2 -sSf https://carthage.software/mago.sh | bash
   

   Verify with:

   mago --version
   

2. First Use Case: Run a basic lint check on your Laravel project:

   mago lint app/
   

3. Configuration: Create a mago.php config file in your project root:

   <?php
   return [
       'rules' => [
           'no-unused-vars' => true,
           'no-deprecated' => true,
       ],
       'paths' => ['app', 'config', 'routes'],
   ];
   

Key Commands

Implementation Patterns

Laravel-Specific Workflows

1. CI Integration: Add to .github/workflows/laravel.yml:

   - name: Run Mago
     run: |
       mago lint --reporting-format=github
       mago analyze --reporting-format=github
       mago fmt --check
   

2. Pre-Commit Hooks: Add to .git/hooks/pre-commit:

   #!/bin/sh
   mago lint --paths=app/config/routes
   

3. Service Provider Integration:

   // app/Providers/AppServiceProvider.php
   public function boot()
   {
       if ($this->app->environment('local')) {
           Artisan::call('mago:lint');
       }
   }
   

Common Patterns

• Path Filtering: Use mago lint --paths=app/Http/Controllers for targeted checks
• Rule Customization: Extend rules in mago.php:

  'rules' => [
      'no-unused-vars' => ['severity' => 'warning'],
      'custom-rule' => true,
  ]
  

• Docker Integration: Use the official image in CI:

  container: ghcr.io/carthage-software/mago:1
  

Gotchas and Tips

Common Pitfalls

1. False Positives in Analysis:

   • Ensure Composer dependencies are installed before running mago analyze
   • Add vendor/ to excluded paths in mago.php if needed

2. Performance Issues:

   • Exclude large directories (e.g., storage/, tests/) from analysis
   • Use --parallel flag for large codebases

3. Configuration Conflicts:

   • Mago respects .magoignore files (similar to .gitignore)
   • Global config (~/.config/mago.php) overrides project config

Debugging Tips

• Verbose Output:

  mago lint -v
  

• Rule Explanation:

  mago explain --rule=no-unused-vars
  

• AST Visualization:

  mago ast app/Http/Controllers/Controller.php
  

Extension Points

1. Custom Rules: Create Rust-based rules by extending the Mago CLI:

   // src/rules/mod.rs
   pub fn register_custom_rules(registry: &mut RuleRegistry) {
       registry.register(Rule::new("custom-rule", CustomRule::new()));
   }
   

2. PHP Integration: Use the mago/analyzer facade in Laravel:

   $results = \Mago\Analyzer::analyze(app_path());
   

3. Reporting Formats: Generate JSON reports for custom processing:

   mago lint --reporting-format=json > mago-report.json
   

Laravel-Specific Quirks

• Route Caching: Exclude bootstrap/cache/ from analysis
• Service Container: Mago automatically detects Laravel's container for dependency resolution
• Artisan Commands: Create custom commands:

  mago make:command MagoCheckCommand