Phpstan Error Formatter Laravel Package

Getting Started

Minimal Setup

1. Install the package via Composer:

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

   Use phpstan/extension-installer for automatic configuration (recommended):

   composer require --dev phpstan/extension-installer
   

2. Configure PHPStan in phpstan.neon:

   parameters:
       errorFormat: ticketswap
       editorUrl: 'phpstorm://open?file=%%file%%&line=%%line%%'  # Replace with your IDE's URL scheme
   

3. Run PHPStan as usual:

   vendor/bin/phpstan analyse src
   

First Use Case

• Debug a type error in your codebase. The formatter will display each error on a single line with:
  • Clickable file/line links (opens directly in your IDE).
  • Highlighted variables, FQCNs (e.g., App\Models\User), and types (e.g., string, int).
  • Truncated but intact file paths (e.g., src/App/.../User.php).

Implementation Patterns

Workflow Integration

1. Daily Static Analysis

   • Run PHPStan with the formatter in your pre-commit hooks or CI pipeline:

     # Example GitHub Actions step
     - name: Run PHPStan
       run: vendor/bin/phpstan analyse --level=10 src
     

   • Use --error-format=ticketswap as a CLI flag for ad-hoc checks:

     vendor/bin/phpstan analyse --error-format=ticketswap app/Http/Controllers/
     

2. IDE-Specific Configuration

   • PhpStorm: Use phpstorm://open?file=%%file%%&line=%%line%%.
   • VS Code: Use vscode://file/%%file%%:%%line%%.
   • Sublime Text: Use subl://open?url=file://%%file%%&line:%%line%%.
   • Terminal-only: Omit editorUrl to rely on clickable links (works in iTerm2, Alacritty, etc.).

3. Team Onboarding

   • Add the formatter to your project’s composer.json dev dependencies and document the editorUrl setup in CONTRIBUTING.md.
   • Example snippet for contributors:

     ## PHPStan Setup
     1. Install dependencies: `composer install`.
     2. Configure your IDE’s URL scheme in `phpstan.neon` (see [editorUrl docs](https://phpstan.org/user-guide/output-format)).
     

4. CI/CD Optimization

   • Cache PHPStan results to avoid reprocessing unchanged files:

     - name: Cache PHPStan
       uses: actions/cache@v3
       with:
         path: ~/.phpstan
         key: phpstan-${{ hashFiles('**/composer.lock') }}
     

   • Use --memory-limit=1G to reduce memory usage in pipelines.

5. Custom Error Highlighting

   • Extend the formatter by overriding its logic in a custom PHPStan extension. Example:

     // app/Extensions/CustomErrorFormatter.php
     use TicketSwap\PhpStanErrorFormatter\TicketSwapErrorFormatter;
     
     class CustomErrorFormatter extends TicketSwapErrorFormatter {
         protected function getHighlightedText(string $text): string {
             $text = parent::getHighlightedText($text);
             // Add custom highlighting (e.g., for Laravel-specific types)
             $text = preg_replace('/\bIlluminate\\\\\\\\.*?\\\\\\\\\\w+/', '<fg=cyan>$0</>', $text);
             return $text;
         }
     }
     

   • Register the custom formatter in phpstan.neon:

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

Gotchas and Tips

Pitfalls

1. Terminal Link Support

   • Issue: Clickable links may not work in all terminals (e.g., Windows cmd, some CI environments).
   • Fix: Use file:// URLs as a fallback or configure editorUrl to open files manually.
   • Test: Run echo -e "\e]8;;https://example.com\aClick me\e]8;;\a" in your terminal to verify support.

2. Path Truncation

   • Issue: Long paths (e.g., /var/www/project/src/.../Deep/Nested/File.php) may truncate visually but remain clickable.
   • Fix: Configure editorUrl to handle absolute paths if needed (e.g., vscode://file/%%file%% works with relative paths).

3. IDE-Specific Quirks

   • PhpStorm: Clickable links may not work in the built-in terminal but function in the editor.
   • VS Code: Ensure the vscode:// URL scheme is enabled in settings.json:

     {
       "terminal.integrated.enablePersistentSessions": true
     }
     

4. Windows Path Handling

   • Issue: Windows paths (e.g., C:\project\src\File.php) may break clickable links.
   • Fix: Use forward slashes in editorUrl:

     editorUrl: 'vscode://file/%%file:gs|\\|/%%:%%line%%'
     

5. PHPStan Level 10+ Noise

   • Issue: Level 10 errors (e.g., unused variables) may clutter output.
   • Fix: Suppress specific rules in phpstan.neon:

     rules:
         PhpStan\Rules\UnusedVariableRule: false
     

Debugging Tips

1. Verify Formatter Activation

   • Check if the formatter is active by running:

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

   • Look for highlighted text and clickable links in the output.

2. Inspect Raw Errors

   • Use --generate-report=json to debug raw PHPStan output:

     vendor/bin/phpstan analyse --generate-report=json > phpstan-report.json
     

   • Validate the formatter’s parsing logic against the raw data.

3. Custom Highlighting Debugging

   • Add debug logs to your custom formatter:

     error_log('Highlighted text: ' . $this->getHighlightedText($text));
     

4. CI/CD Logging

   • If errors disappear in CI, ensure the terminal supports ANSI colors:

     env:
       FORCE_COLOR: 1  # Ensures color output in CI
     

Extension Points

1. Override Highlighting Rules

   • Extend TicketSwapErrorFormatter to add custom regex patterns for highlighting (e.g., Laravel facades):

     protected function getHighlightedText(string $text): string {
         $text = parent::getHighlightedText($text);
         $text = preg_replace('/\bFacade\\\\\\\\.*?::\w+/', '<fg=yellow>$0</>', $text);
         return $text;
     }
     

2. Custom Error Grouping

   • Use PHPStan’s report parameter to group errors by file:

     parameters:
         report: 'grouped'
     

3. Integrate with Git Hooks

   • Example pre-commit hook to run PHPStan with the formatter:

     # .git/hooks/pre-commit
     #!/bin/sh
     vendor/bin/phpstan analyse --error-format=ticketswap --level=8 --no-progress
     if [ $? -ne 0 ]; then
         echo "PHPStan errors found. Fix them before committing."
         exit 1
     fi
     

4. Combine with Other Tools

   • Pipe PHPStan output to grep for specific errors:

     vendor/bin/phpstan analyse --error-format=ticketswap 2>&1 | grep "Parameter #1"
     

Configuration Quirks

1. Editor URL Schemes

   • Mac (Finder): open %%file%%:%%line%%.
   • Linux (Nautilus): nautilus %%file%%:%%line%%.
   • JetBrains IDEs: idea://open?file=%%file%%&line=%%line%%.

2. Disable Path Truncation

   • Override the formatter’s path-truncating logic by extending the class and setting:

     protected bool $truncatePaths = false;
     

3. Force Decorated Output

   • Ensure terminal supports ANSI colors by setting:

     parameters:
         colors: true
     

4. Windows-Specific Fixes

   • Use str_replace to normalize paths in custom formatters:

     $filePath = str_replace('\\', '/', $filePath