Phpstan Friendly Formatter Laravel Package

Getting Started

Install the package via Composer:

composer require --dev yamadashy/phpstan-friendly-formatter

Then run PHPStan with the formatter using the --formatter option:

vendor/bin/phpstan --formatter=friendly

If you use phpstan.neon (e.g., phpstan.neon.dist), you can configure it permanently:

parameters:
    formatting:
        formatter: friendly

This is the fastest way to see immediate improvements in output readability—no code changes required. Start with local development, then adopt it in CI for consistent feedback. With v1.4.0+, CI-specific annotations (e.g., GitHub PR diff annotations or TeamCity build log entries) appear automatically when detected—no configuration needed.

Implementation Patterns

• Local Development: Add --formatter=friendly to your composer.json scripts (e.g., "phpstan": "phpstan analyse src --formatter=friendly") for quick, actionable feedback.
• CI Pipelines: Use the formatter universally in GitHub Actions, TeamCity, GitLab CI, etc. Now enhanced: errors automatically surface as annotations in GitHub PR diffs or TeamCity logs without extra setup.
• Custom PHPStan Config: Anchor usage with a phpstan.neon include in your root, enabling formatter adoption across repos and developers without per-command boilerplate.
• Combined with Debugging Tools: Pair with --debug or --xdebug flags—the formatter renders verbose stack traces cleanly while preserving structured data for CI tools.
• Team Standardization: Share formatter config in docs to align on how errors are displayed. Since v1.4.0, teams benefit from consistent, enriched summaries (error breakdown by identifier, polished stats) and CI-aware reporting out-of-the-box.
• IDE Integration: In PhpStorm or other IDEs, configure PHPStan runs to pass --formatter=friendly. Now benefits from CI-adjacent output even locally (e.g., rich summaries), and ensures local logs match CI verbosity levels.

Gotchas and Tips

• ⚠️ Formatter name is friendly, not yamadashy/phpstan-friendly-formatter—no namespace in --formatter= argument.
• 🧪 No impact on analysis: It only styles output—ensure your phpstan.neon rules and level settings remain unchanged. If you see fewer errors, double-check it’s not being suppressed by log redirection.
• 🔍 Output is terminal-friendly by default: Some CI environments (e.g., older Docker or minimal shells) may truncate colors; use --no-ansi or set PHPSTAN_FORMATTER_COLOR=0.
• 🤖 CI detection is automatic: GitHub Actions and TeamCity annotations appear without configuration when running in those environments. If annotations don’t appear, verify your CI job runs the formatter directly (not via third-party wrappers that may strip annotations).
• 📊 New v1.4.0 summaries: Error breakdown by identifier and enhanced statistics are now shown by default in both local and CI runs—useful for identifying high-frequency errors during root-cause analysis.
• 🧰 Extension points: While the formatter itself remains minimal, it now explicitly supports machine-readable output for CI tools. You can safely chain it with tools like phpstan-to-baseline—error counts and paths are preserved even when annotations are active.
• 🐛 Bug fix reminder: v1.4.0 resolves a DI injection issue with relativePathHelper—update if you’ve encountered cryptic PHPStan startup errors.
• 🚀 Pro tip: In PR reviews, GitHub annotations now appear directly on changed lines—reviewers can click through to the exact error source. This works best when combined with phpstan --memory-limit=2G for large repos.