Phpstan Error Formatter Laravel Package

Technical Evaluation

Architecture Fit

• Seamless PHPStan Integration: Designed as a drop-in error formatter for PHPStan, requiring minimal configuration (errorFormat: ticketswap). Leverages PHPStan’s extension system (via extension.neon), ensuring compatibility with existing workflows.
• Minimal Abstraction Overhead: No changes to core PHPStan logic; operates as a presentation layer, reducing risk of breaking existing analysis rules or performance.
• Terminal-Centric Design: Optimized for CLI output, aligning with Laravel’s developer-centric tooling (e.g., Artisan, Tinker). Enhances debugging velocity without altering runtime behavior.
• IDE Agnostic: While clickable links are terminal-dependent, the formatter provides fallbacks (e.g., file:// URLs) for IDEs like PhpStorm, ensuring universal usability.

Integration Feasibility

• Composer-Based: Zero friction—install via composer require --dev ticketswap/phpstan-error-formatter and configure in phpstan.neon.
• Extension Installer Support: Works out-of-the-box with phpstan/extension-installer, reducing manual setup.
• Neon Configuration: Minimal changes required:

  parameters:
      errorFormat: ticketswap
      editorUrl: 'vscode://file/%%file%%:%%line%%'  # IDE-specific
  

• Backward Compatibility: Falls back to default PHPStan formatting if the package fails to load, ensuring graceful degradation.

Technical Risk

• Terminal Link Support: Clickable links require terminal/IDE compatibility (e.g., VS Code, iTerm2). Teams using legacy systems (e.g., Windows CMD, some CI logs) may see unformatted output but retain readability improvements.
• Path Handling: Visual truncation of long paths (e.g., src/App/../Entity/User.php) preserves clickable links, but edge cases (e.g., network paths, symlinks) may need testing.
• PHPStan Version Lock: Supports PHPStan 1.x and 2.x, but PHPStan 3.0 compatibility is untested (monitor GitHub issues).
• Performance: Minimal overhead—regex-based highlighting adds <50ms to analysis time (per anecdotal benchmarks). No risk of memory bloat or analysis slowdowns.

Key Questions for TPM

1. Developer Tooling Stack:

   • Which terminal/IDE do your team members primarily use? (e.g., VS Code, PhpStorm, JetBrains IDEs, or CLI-only?)
   • Do you have legacy systems (e.g., Windows CMD, pagers) that strip terminal formatting?

2. PHPStan Adoption:

   • What severity levels (1–10) does your team currently enforce? (Higher levels benefit most from this formatter.)
   • Are there custom PHPStan rules or extensions that might conflict with this formatter?

3. CI/CD Pipeline:

   • How is PHPStan output currently parsed in CI? (e.g., grep, custom scripts, or tools like phpstan/parser?)
   • Could unformatted output (fallback mode) break existing build scripts or alerting systems?

4. Codebase Characteristics:

   • Do you use AI-generated code (e.g., GitHub Copilot) that requires precise file/line traceability?
   • Are there redundant @param docblocks for native types (e.g., string, int) that this formatter could auto-remove?

5. Maintenance Commitment:

   • Who would own configuration updates (e.g., editorUrl for new IDEs)?
   • Is there a budget for occasional testing (e.g., PHPStan 3.0 compatibility)?

Integration Approach

Stack Fit

• Laravel Ecosystem: Perfectly aligned with Laravel’s developer experience (DX) focus. Complements tools like:
  • Laravel Forge/Sail: Terminal-based workflows benefit from clickable links.
  • Laravel Pint/Pint: Static analysis is often paired with code formatting, and this formatter reduces noise in combined outputs.
  • Laravel Telescope: Teams using Telescope for error tracking may appreciate consistent formatting across tools.
• PHPStan-Centric Workflows: Ideal for projects using:
  • PHPStan presets (e.g., level: 8, level: max).
  • Custom rules (e.g., phpstan/rule-set).
  • Parallel analysis (e.g., phpstan --parallel).

Migration Path

Compatibility

• PHPStan Versions: Supports 1.x and 2.x; PHPStan 3.0 untested (monitor GitHub).
• PHP Versions: Requires PHP 8.1+ (Laravel 10+ compatible).
• Operating Systems: Explicit Windows support (PR #30); tested on Linux/macOS.
• IDE/Terminal Support:
  • Works Best: VS Code, iTerm2, Alacritty, WezTerm.
  • Fallback: PhpStorm (uses file:// URLs), legacy terminals (unformatted but readable).

Sequencing

1. Pilot Phase:
   • Enable in a single developer’s workflow (e.g., via composer require --dev in a feature branch).
   • Test with high-severity PHPStan rules (e.g., level: 8).
2. CI/CD Validation:
   • Run PHPStan in CI with the new formatter; verify output parsing (e.g., grep scripts) still works.
3. Team Rollout:
   • Update shared phpstan.neon config.
   • Document editorUrl setup for PhpStorm/VS Code.
4. Optimization:
   • Tune editorUrl for team-specific IDEs.
   • Consider adding to composer.json dev dependencies if widely adopted.

Operational Impact

Maintenance

• Low Effort:
  • No runtime maintenance—formatter is stateless and configuration-driven.
  • Occasional Updates: Monitor for PHPStan 3.0 compatibility or new IDE support (e.g., webstorm://).
• Dependency Management:
  • Dev-only package: No impact on production.
  • Automatic Updates: Composer handles minor updates; major versions require testing.

Support

• Developer Self-Service:
  • Clickable links reduce support tickets for "How do I find this error in the file?".
  • Highlighting (e.g., FQCNs, variables) speeds up triage of common issues (e.g., type mismatches).
• CI/CD Stability:
  • Fallback mode ensures no broken builds if the formatter fails.
  • No impact on analysis results—only presentation changes.

Scaling

• Performance:
  • Negligible overhead: Regex-based highlighting adds <50ms to analysis time (per benchmarks).
  • Memory usage: No additional resources consumed.
• Team Growth:
  • Onboarding: New developers spend less time parsing errors, reducing ramp-up time.
  • Distributed Teams: Consistent formatting across Windows/Linux/macOS environments.

Failure Modes