Mago Laravel Package

Getting Started

Minimal Setup for Laravel Projects

1. Installation:

   composer require carthage-software/mago --dev
   

   Or via the official shell script for global CLI access.

2. First Run:

   mago lint app/ --fix
   

   • Flags like --fix auto-corrects lint issues (e.g., formatting, redundant code).
   • Use mago analyze for static analysis (e.g., type safety, Laravel-specific rules).

3. Configuration: Create mago.php in your project root:

   return [
       'integrations' => ['laravel'],
       'rules' => [
           'laravel/assertions' => true,
           'laravel/queries' => true,
       ],
   ];
   

   • Enable Laravel-specific rules (e.g., laravel/assertions for assertEquals best practices).

4. CI Integration: Add to .github/workflows/ci.yml:

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

Implementation Patterns

Daily Workflows

1. Pre-Commit Hooks: Use mago via php-cs-fixer or husky:

   mago lint --fix --fail-level=error
   

   • Tip: Cache results with --baseline to skip unchanged files.

2. Static Analysis in Development:

   mago analyze --no-progress --json > mago-results.json
   

   • Parse JSON output for IDE integration (e.g., PHPStorm via mago-language-server).

3. Laravel-Specific Patterns:

   • Test Assertions: Enable laravel/assertions to catch assertEquals mismatches.
   • Query Rules: Use laravel/queries to enforce DB::table() over query builder.
   • Fake Helpers: Auto-fix fake()-> calls with --fix.

4. Custom Rules: Extend rules via mago.php:

   'rules' => [
       'no-redundant-variable' => ['severity' => 'warning'],
       'custom/rule' => true, // Enable community rules
   ],
   

5. IDE Integration:

   • Use mago-language-server for real-time diagnostics:

     mago language-server --stdio
     

   • Configure VSCode’s php-intelephense to use Mago’s AST.

Integration Tips

• Composer Scripts:

  {
    "scripts": {
      "mago": "mago lint --fix",
      "mago:analyze": "mago analyze --no-progress"
    }
  }
  

  Run with composer mago.

• GitHub Actions:

  - name: Mago Static Analysis
    run: mago analyze --fail-level=error --json
  

  Upload mago-results.json as an artifact for PR reviews.

• Symlinked Vendors: Mago 1.29+ supports symlinked vendor/ via --follow-symlinks.

Gotchas and Tips

Pitfalls

1. False Positives:

   • Generic Type Errors: Disable sound-generic-checking in mago.php if needed:

     'analyzer' => ['sound-generic-checking' => false],
     

   • Redundant Null Checks: Ignore specific lines with:

     // mago:ignore redundant-null-coalesce
     $value ??= $default;
     

2. Performance:

   • Exclude node_modules/ or vendor/ from analysis:

     mago analyze --ignore="node_modules|vendor"
     

   • Use --parallel for large codebases (Rust-backed, so fast by default).

3. Configuration Quirks:

   • Distributed Config: Mago 1.29+ restores mago.dist support. Place shared rules here.
   • Regex Ignores: Use pattern = "..." in mago.php to ignore issues by text:

     'analyzer' => ['ignore' => ['pattern' => '.*redundant-logical-operation.*']],
     

4. Laravel-Specific:

   • Fake Helpers: Auto-fix may break if fake()-> is used in strings. Use --no-fix for these cases.
   • WordPress Rules: Require explicit integration:

     'integrations' => ['wordpress'],
     

Debugging

• Verbose Output:

  mago analyze --verbose
  

  Shows Rust-backed parsing steps.

• AST Visualization:

  mago ast app/Http/Controllers/Controller.php
  

  Inspect the Abstract Syntax Tree for complex issues.

• Baseline Management:

  • Prune Stale Entries:

    mago lint --remove-outdated-baseline-entries
    

  • Version Drift: Fail on minor/patch updates:

    'cli' => ['version-drift-fail-level' => 'minor'],
    

Extension Points

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

   // src/rules/no_fully_qualified.rs
   #[derive(Debug, Default)]
   pub struct NoFullyQualified;
   
   impl Rule for NoFullyQualified {
       fn check(&self, node: &Node) -> Vec<Diagnostic> {
           // Implement logic here
       }
   }
   

2. Language Server: Extend diagnostics via mago-language-server’s onDiagnostic hook.

3. Formatter: Override defaults in mago.php:

   'formatter' => [
       'echo_tags' => 'align',
       'constructor_parens' => 'preserve',
   ],
   

Pro Tips

• Closure Names: Mago 1.29+ shows human-readable closure names (e.g., {closure:src/foo.php:12:5}).
• WordPress Security: Enable wordpress integration for rules like nonce-verification.
• Symlinked Vendors: Use --follow-symlinks for monorepos or custom setups.