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. In v1.5.0, type mismatch errors get expected/actual type highlighting (green = declared, red = found) out of the box, so your first run against a codebase with type errors is noticeably easier to scan.

Implementation Patterns

• Local Development: Add --formatter=friendly to your composer.json scripts (e.g., "phpstan": "phpstan analyse src --formatter=friendly") for quick, actionable feedback. Since v1.5.0, type mismatches render with expected types in green and actual types in red, making fixes faster to spot.
• CI Pipelines: Use the formatter universally in GitHub Actions, TeamCity, GitLab CI, etc. Errors automatically surface as annotations in GitHub PR diffs or TeamCity logs without extra setup. Type highlighting also applies within CI annotation messages when supported, so reviewers see the declared-vs-actual distinction inline.
• 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. Teams benefit from consistent, enriched summaries (error breakdown by identifier, polished stats), CI-aware reporting, and now role-based type coloring so everyone reads the same visual grammar: green is what the code declares, red is what was actually found.
• IDE Integration: In PhpStorm or other IDEs, configure PHPStan runs to pass --formatter=friendly. Benefits from CI-adjacent output locally (e.g., rich summaries and type highlighting) 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.
• 🎨 Type highlighting is role-based, not positional (v1.5.0): in messages like Return type int of Child::m() is not covariant with return type string of Parent::m(), the parent's type is green even when it appears later in the sentence. Read green as "declared/expected" and red as "found/actual" regardless of ordering.
• 🧩 Highlighting is best-effort: only known message shapes are colored (e.g., expects X, Y given, should return X but returns Y, (X) does not accept Y, PHPDoc/native incompatibilities, covariance/contravariance mismatches, invoked with N parameters, M required). Unrecognized messages are printed unchanged, and no configuration is needed.
• 🔍 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).
• 📊 Rich summaries (v1.4.0+): Error breakdown by identifier and enhanced statistics are shown by default in both local and CI runs—useful for identifying high-frequency errors during root-cause analysis.
• 🧰 Extension points: The formatter 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. Type highlighting is purely decorative and does not alter message text used by downstream parsers.
• 🐛 PHPStan 2.2.x compatibility (v1.5.0): Tests were updated for the AnalysisResult constructor changes in PHPStan 2.2.x. If you hit unexpected constructor or DI errors on recent PHPStan versions, upgrade.
• 🐛 Prior fix retained: v1.4.0 resolves a DI injection issue with relativePathHelper—make sure you're on 1.4.0+ if you hit 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, with expected/actual types visually distinguished. This works best when combined with phpstan --memory-limit=2G for large repos.