Phpstan Error Formatter Laravel Package

Getting Started

Minimal Setup

1. Install the package in your Laravel project (or any PHP project using PHPStan):

   composer require --dev ticketswap/phpstan-error-formatter
   

2. Enable the formatter in your phpstan.neon config:

   parameters:
       errorFormat: ticketswap
   

3. Configure editor URLs (optional but recommended for IDE integration):

   parameters:
       editorUrl: 'vscode://file/%%file%%:%%line%%'  # VS Code
       # OR
       editorUrl: 'phpstorm://open?file=%%file%%&line=%%line%%'  # PhpStorm
   

First Use Case

Run PHPStan with the new formatter:

./vendor/bin/phpstan analyse

Expected Output:

• Each error appears on its own line with clickable file/line links (if your terminal supports it).
• No wrapped tables—errors are unwrapped and scannable.
• Highlighted types (e.g., string, App\Models\User) and variables for quick visual parsing.

Implementation Patterns

Workflow Integration

1. Daily Static Analysis

   • Replace default PHPStan output with this formatter in your CI/CD pipeline and local workflows.
   • Example GitHub Actions step:

     - name: Run PHPStan
       run: ./vendor/bin/phpstan analyse --error-format=ticketswap
     

2. IDE-Specific Optimizations

   • VS Code: Use vscode://file/%%file%%:%%line%% for direct file/line jumps.
   • PhpStorm: Use phpstorm://open?file=%%file%%&line=%%line%% for seamless navigation.
   • Terminals (iTerm2/Alacritone): Clickable links work out-of-the-box.

3. Team Onboarding

   • Add a .phpstan.neon template to your project’s templates/ folder to enforce consistent formatting across new developers.
   • Example template:

     includes:
         - vendor/ticketswap/phpstan-error-formatter/extension.neon
     parameters:
         errorFormat: ticketswap
         editorUrl: 'vscode://file/%%file%%:%%line%%'
     

4. CI/CD Pipeline

   • Fail builds on errors while leveraging the formatter’s clean output for debugging:

     ./vendor/bin/phpstan analyse --error-format=ticketswap --level=8 --no-progress
     

   • Use --generate-baseline to baseline errors without cluttering logs.

5. Custom PHPStan Rulesets

   • Combine with custom rules (e.g., phpstan-rules) while keeping output readable:

     includes:
         - vendor/ticketswap/phpstan-error-formatter/extension.neon
         - rulesets/custom-rules.neon
     parameters:
         errorFormat: ticketswap
     

Laravel-Specific Tips

• Artisan Integration: Add a custom Artisan command to run PHPStan with the formatter:

  // app/Console/Commands/RunPhpStan.php
  namespace App\Console\Commands;
  
  use Illuminate\Console\Command;
  
  class RunPhpStan extends Command
  {
      protected $signature = 'phpstan:analyse';
      protected $description = 'Run PHPStan with the TicketSwap formatter';
  
      public function handle()
      {
          $this->call('vendor:publish', ['--tag' => 'phpstan-config']);
          $this->call('phpstan', [
              'analyse',
              '--error-format=ticketswap',
              '--level=8',
          ]);
      }
  }
  

  Register it in app/Console/Kernel.php:

  protected $commands = [
      Commands\RunPhpStan::class,
  ];
  

• Laravel Forge/Envoyer: Configure your deploy script to run PHPStan with the formatter:

  ./vendor/bin/phpstan analyse --error-format=ticketswap --memory-limit=1G
  

Gotchas and Tips

Pitfalls

1. Terminal/IDE Compatibility

   • Issue: Clickable links may not work in all terminals (e.g., Windows cmd or older IDEs).
   • Fix: Use file:/// URLs as a fallback (default behavior). Test with:

     echo -e "\e]8;;file:///path/to/file.php\aClick here\e]8;;\a"
     

   • Workaround: For PhpStorm, use file:/// paths explicitly:

     parameters:
         editorUrl: 'file://%%file%%'
     

2. Path Truncation

   • Issue: Long paths (e.g., /var/www/project/src/...) are truncated visually but remain clickable.
   • Fix: Disable truncation by setting truncatePaths: false in extension.neon (if supported in future versions).

3. Highlighting Edge Cases

   • Issue: Some types (e.g., array<int, string>, mixed) may not be highlighted.
   • Fix: Manually escape or update the formatter’s regex patterns (see source).

4. CI/CD Output Parsing

   • Issue: Some CI systems (e.g., GitHub Actions) may misinterpret clickable links as errors.
   • Fix: Use --no-progress and --no-interaction flags to ensure clean output:

     ./vendor/bin/phpstan analyse --error-format=ticketswap --no-progress
     

5. PHPStan Level 10+

   • Issue: Stricter PHPStan levels (e.g., 10) may produce overly verbose errors.
   • Fix: Combine with --memory-limit and --parallel for better performance:

     ./vendor/bin/phpstan analyse --level=10 --error-format=ticketswap --parallel --memory-limit=2G
     

Debugging Tips

1. Verify Formatter is Active Run PHPStan with --debug to confirm the formatter is loaded:

   ./vendor/bin/phpstan analyse --debug
   

   Look for Using error formatter: ticketswap.

2. Check Editor URL Support Test your editorUrl configuration by running:

   echo "file://$(pwd)/app/Models/User.php" | xargs open  # macOS
   

   Or manually click the link in your terminal.

3. Customize Highlighting Extend the formatter by overriding its regex patterns. Example:

   // In a custom extension.neon
   services:
       ticketswap.errorFormatter:
           class: TicketSwap\ErrorFormatter\TicketSwapErrorFormatter
           arguments:
               - '%parameters.errorFormat%'
               - '%parameters.editorUrl%'
               - '%parameters.truncatePaths%'  # Add custom config
   

4. Performance Tuning

   • For large codebases, use --parallel and --memory-limit:

     ./vendor/bin/phpstan analyse --parallel --memory-limit=2G --error-format=ticketswap
     

   • Exclude tests or specific directories to speed up runs:

     excludeFiles:
         - tests/**
         - vendor/**
     

Extension Points

1. Custom Error Formatting Extend TicketSwapErrorFormatter to add custom highlighting or post-processing:

   namespace App\Services;
   
   use TicketSwap\ErrorFormatter\TicketSwapErrorFormatter;
   
   class CustomErrorFormatter extends TicketSwapErrorFormatter
   {
       protected function decorateMessage(string $message): string
       {
           $message = parent::decorateMessage($message);
           // Add custom logic (e.g., colorize specific errors)
           return str_replace('Deprecated', "\033[33mDeprecated\033[0m", $message);
       }
   }
   

   Register it in extension.neon:

   services:
       ticketswap.errorFormatter:
           class: App\Services\CustomErrorFormatter
   

2. Integrate with Laravel Logging Pipe PHPStan output to Laravel’s log channel for centralized error tracking:

   ./vendor/bin/phpstan analyse --error-format=ticketswap 2>&1 | php artisan log:read
   

   Or create a custom command to log errors to the database.

3. Slack/Teams Notifications Use the formatter’s output to trigger notifications in Slack/Teams:

   // In a custom Artisan command
   $output = shell_exec('phpstan analyse --error-format=ticketswap --no-progress');
   $this->sendSlackNotification($output);