Mago Laravel Package

Getting Started

Minimal Setup

1. Install Mago via the official installer:

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

   Or via Composer:

   composer require carthage-software/mago --dev
   

2. Initialize Configuration: Run in your Laravel project root:

   mago init
   

   This generates a mago.toml file with Laravel-specific defaults.

3. First Lint Run:

   mago lint
   

   Fix critical issues immediately:

   mago lint --fix
   

Key Laravel-Specific Integrations

Enable framework-specific rules in mago.toml:

[linter]
integrations = ["laravel", "phpunit"]

Implementation Patterns

Workflow Integration

1. CI/CD Pipeline: Add to .github/workflows/lint.yml:

   - name: Lint with Mago
     run: mago lint --minimum-fail-level=error
   

2. Pre-Commit Hook: Use mago lint --fix in a pre-commit hook (via husky or pre-commit):

   mago lint --fix --dry-run  # Preview changes
   

3. IDE Integration: Configure your IDE (PHPStorm/VSCode) to run mago lint on save via:

   • PHPStorm: Settings > Tools > PHP > Run inspection by
   • VSCode: Extensions like "Mago" (if available) or custom tasks.

Common Patterns

• Rule-Specific Fixes:

  mago lint --fix --rule=prefer-static-closure
  

• Excluding Tests:

  [linter.rules]
  no-global = { exclude = ["tests/**"] }
  

• Baseline Management: Generate a baseline for new projects:

  mago lint --baseline=baseline.toml
  

Laravel-Specific Tips

1. Route/Controller Rules: Enable Laravel’s route validation rules:

   [linter.rules]
   laravel-route-return-type = { level = "warning" }
   

2. Migration Checks: Exclude generated migrations:

   [linter]
   excludes = ["database/migrations/*_timestamp.php"]
   

3. Service Container Rules: Detect unused service bindings:

   mago lint --rule=unused-service-binding
   

Gotchas and Tips

Pitfalls

1. Performance Spikes:

   • Issue: Large projects may hit Rust thread limits.
   • Fix: Adjust RUSTFLAGS in CI:

     export RUSTFLAGS="-C target-cpu=native"
     

2. False Positives in Legacy Code:

   • Issue: Rules like no-goto may flag legacy header()/exit() calls.
   • Fix: Use rule-specific excludes:

     [linter.rules]
     no-goto = { exclude = ["src/Legacy/**"] }
     

3. Baseline Drift:

   • Issue: Frequent baseline updates can pollute history.
   • Fix: Use --baseline-variant=loose for CI:

     mago lint --baseline=baseline.toml --baseline-variant=loose
     

Debugging

• Verbose Output:

  mago lint --verbose
  

• Rule Explanation:

  mago lint --explain cyclomatic-complexity
  

• AST Visualization:

  mago ast --file=app/Http/Controllers/ExampleController.php
  

Extension Points

1. Custom Rules: Write Rust-based rules using Mago’s rule SDK.

2. Laravel-Specific Rules: Extend the laravel integration by contributing to Mago’s integrations.

3. CI-Specific Configs: Use environment variables to override configs:

   MAGO_MINIMUM_FAIL_LEVEL=warning mago lint
   

Laravel Quirks

• Facade Static Calls: Mago may flag Route::get() as "ambiguous". Suppress with:

  [linter.rules]
  ambiguous-function-call = { exclude = ["routes/**"] }
  

• Dynamic Properties: Rules like no-dynamic-properties may conflict with Laravel’s dynamic properties (e.g., $request->input()). Exclude:

  [linter.rules]
  no-dynamic-properties = { exclude = ["app/Http/**"] }
  

• Service Provider Boot Methods: Mago’s unused-method rule may flag boot() methods. Whitelist:

  [linter.rules]
  unused-method = { exclude = ["**/Providers/*Provider.php"] }