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 extension via phpstan/extension-installer (recommended) or manually include extension.neon in your PHPStan config:

   includes:
       - vendor/ticketswap/phpstan-error-formatter/extension.neon
   

3. Configure PHPStan to use the new formatter in your phpstan.neon:

   parameters:
       errorFormat: ticketswap
       editorUrl: 'phpstorm://open?file=%%file%%&line=%%line%%'  # or 'vscode://file/%%file%%:%%line%%'
   

First Use Case

Run PHPStan with your existing configuration:

./vendor/bin/phpstan analyse

• Immediate benefit: Errors now display unwrapped, with clickable file/line links (if your terminal/IDE supports it).
• Example output:

  [ERROR] Class App\Models\User has no property $nonExistentProperty
  src/App/Models/User.php:15:10
  

Implementation Patterns

Workflow Integration

1. Daily Static Analysis

   • Replace default PHPStan output with this formatter for local development, CI pipelines, and code reviews.
   • CI/CD: Add to your pipeline (e.g., GitHub Actions) to ensure consistent, readable error output:

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

2. Editor/IDE-Specific Configurations

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

3. Team Onboarding

   • Document the formatter in your team’s CONTRIBUTING.md or DEVELOPMENT.md to ensure consistency.
   • Example snippet for docs:

     ## PHPStan Errors
     Run `phpstan analyse` for static analysis. Errors include clickable file/line links:
     - **PhpStorm**: Click the link to open the file.
     - **VS Code**: Click to jump to the line.
     - **Terminal**: Copy-paste the path/line into your editor.
     

4. Custom PHPStan Rulesets

   • Combine with strict rulesets (e.g., level: 8) for maximum benefit:

     includes:
         - vendor/ticketswap/phpstan-error-formatter/extension.neon
     level: 8
     parameters:
         errorFormat: ticketswap
     

5. Automated Cleanup of Redundant Docblocks

   • The formatter automatically removes @param docblocks for native types (e.g., string, int), reducing noise in AI-generated or legacy code.

Laravel-Specific Tips

1. Artisan Command Integration

   • Extend Laravel’s phpstan:analyze command (if using laravel-pint or similar) to enforce the formatter:

     // app/Console/Commands/AnalyzeCode.php
     protected function runPhpStan()
     {
         $command = 'phpstan analyse --error-format=ticketswap';
         $this->callSilently('vendor:publish', ['--provider' => 'Laravel\Pint\PintServiceProvider']);
         $this->call('cache:clear');
         $this->line($this->runCommand($command));
     }
     

2. Forge/Envoyer Deployments

   • Add PHPStan to your deployment pipeline with the formatter:

     # In your Envoyer recipe or Forge deploy script
     composer install --no-dev
     composer require --dev ticketswap/phpstan-error-formatter
     ./vendor/bin/phpstan analyse --error-format=ticketswap
     

3. Laravel IDE Helper Integration

   • If using barryvdh/laravel-ide-helper, run PHPStan before generating helpers to catch issues early:

     ./vendor/bin/phpstan analyse --error-format=ticketswap
     ./vendor/bin/php artisan ide-helper:generate
     

Gotchas and Tips

Pitfalls

1. Terminal/IDE Compatibility

   • Issue: Clickable links may not work in all terminals (e.g., Windows Command Prompt, older PhpStorm versions).
   • Fix: Use file:/// URLs as a fallback (configured via editorUrl):

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

   • Workaround: Document manual navigation steps for unsupported environments.

2. Path Truncation in AI Environments

   • Issue: Long paths (e.g., /Volumes/CS/www/src/...) may break clickable links if truncated.
   • Fix: The formatter automatically detects AI agents (e.g., GitHub Copilot) and preserves full paths (since PR 36). No action required.

3. Line Number 0 Edge Case

   • Issue: Errors with line: 0 (e.g., from phpstan:no-extra-args) may display incorrectly.
   • Fix: The formatter skips line numbers for 0 (since PR 31). No configuration needed.

4. Custom Type Highlighting Limitations

   • Issue: Naive regex highlighting may miss edge cases (e.g., Class::Constant or stdClass).
   • Fix: The package actively improves these cases (e.g., PR 21 for Stringable, PR 24 for stdClass). Update regularly:

     composer update ticketswap/phpstan-error-formatter
     

5. Windows Path Handling

   • Issue: Windows paths (e.g., C:\project\src\...) may not work with file:// URLs.
   • Fix: Use vscode://file/ or phpstorm://open?file= with forward slashes (the formatter handles this automatically).

Debugging Tips

1. Verify Formatter Activation

   • Run PHPStan with --verbose to confirm the formatter is loaded:

     ./vendor/bin/phpstan analyse --verbose
     

   • Look for:

     [PHPStan\Analyser\Error] Using error formatter: ticketswap
     

2. Check editorUrl Configuration

   • If links don’t work, validate your editorUrl:
     • PhpStorm: phpstorm://open?file=%%file%%&line=%%line%%
     • VS Code: vscode://file/%%file%%:%%line%%
     • Manual Fallback: file://%%file%% (may require opening in browser).

3. Override Formatter Temporarily

   • Test the default formatter to isolate issues:

     ./vendor/bin/phpstan analyse --error-format=default
     

4. Handle False Positives

   • If the formatter misses highlighting (e.g., custom types), manually add regex patterns to extension.neon:

     services:
         TicketSwap\PhpStanErrorFormatter\TicketSwapErrorFormatter:
             decorate: true
             decorateWith: @phpstan.errorFormatter
             parameters:
                 customTypes:
                     - 'My\\Custom\\Type'
     

Extension Points

1. Custom Highlighting Rules

   • Extend the formatter’s regex patterns by subclassing TicketSwapErrorFormatter:

     // app/Providers/AppServiceProvider.php
     use TicketSwap\PhpStanErrorFormatter\TicketSwapErrorFormatter;
     
     public function register()
     {
         $this->app->bind(TicketSwapErrorFormatter::class, function ($app) {
             $formatter = new TicketSwapErrorFormatter();
             $formatter->addCustomType('My\\Custom\\Type');
             return $formatter;
         });
     }
     

2. Modify Error Output

   • Override the formatErrors() method to add pre/post-processing:

     class CustomErrorFormatter extends TicketSwapErrorFormatter
     {
         public function formatErrors(array $errors): string
         {
             $output = parent::formatErrors($errors);
             return "[CUSTOM] $output"; // Prefix all errors
         }
     }
     

   • Bind it in extension.neon:

     services:
         CustomErrorFormatter:
             class: App\Services\CustomErrorFormatter
             decorate: true
             decorateWith: @phpstan.errorFormatter
     

3. Integrate with Laravel Logging

   • Log PHPStan errors to Laravel’s channel for centralized monitoring:

     // In your PHPStan command or service