Phpinsights Formatter Laravel Package

Getting Started

• Install as a dev dependency alongside PHP Insights itself:

  composer require --dev nunomaduro/phpinsights soyhuce/phpinsights-formatter
  

  The formatter is not a runtime dependency — keep it in require-dev so it doesn't ship to production.
• Publish/verify config first: php vendor/bin/phpinsights --config-path=config/insights.php (or php artisan insights if you use the Laravel wrapper). This is where presets, excluded paths, and thresholds live before you touch formatting.
• Look at the package README's formatter list first — the package adds formatters, not new analysis rules. The value is entirely in the --format= flag.
• First use case: run the suite once and dump a machine-readable report to disk:

  php vendor/bin/phpinsights --no-interaction --format=<formatter> > build/insights.xml
  

  Wire that single command into CI, upload build/insights.xml as an artifact, and you're done — the local workflow stays php vendor/bin/phpinsights.

Implementation Patterns

• CI reporting pipeline. The canonical pattern is: analyse once, emit a report file, feed it to your CI's native report consumer (JUnit/checkstyle-style annotators, GitLab code quality artifacts, PR annotations). Configure it as a distinct composer script so CI and humans run the identical command:

  "scripts": {
    "insights": "phpinsights --no-interaction",
    "insights:report": "phpinsights --no-interaction --format=<formatter> --quiet > build/insights.xml"
  }
  

• Analyse cheaply, fail separately. Run insights:report with a report-only intent (collect and publish) and let a second, plain insights invocation own the pass/fail gate. This keeps the CI report populated even on red builds, which is exactly when you want it.
• Split formatters per surface. Use the default console output for the developer-facing log and the formatter only for the artifact. Don't try to make one output serve both — annotations and prose logs have different readers.
• Baseline-friendly rollout. On an existing codebase, add the report formatter before enforcing thresholds. You get visibility in PRs immediately while config/insights.php still has permissive min-quality/min-complexity/min-architecture/min-style values, then ratchet them up over successive PRs.
• Keep it out of the request cycle. Everything here belongs in CI and local git hooks, never in application bootstrapping. No service provider wiring, no queued jobs.

Gotchas and Tips

• Formatter name discovery. The --format= value must match a formatter the package registers; a typo produces a generic "invalid format" error rather than a list. Check the README/src/ for the exact identifiers before debugging your YAML.
• Exit codes truncate reports. PHP Insights returns non-zero when quality gates fail, which in shell pipelines can drop output. Use || true (or capture then re-raise) when you specifically want the artifact to survive a failing build.
• --no-interaction is mandatory in CI, otherwise the run can hang waiting on a prompt.
• Relative paths in reports. File paths are emitted relative to the working directory of the process. Run the formatter from the repo root, or CI consumers will fail to map findings back to diffs.
• Version coupling. This package tracks PHP Insights' formatter contract; pin both in composer.json and bump them together. A PHP Insights major/minor bump can silently change what the formatter receives.
• On this release (2.1.0): purely maintenance — Dependabot bumps for GitHub Actions (actions/checkout 3→4, ramsey/composer-install 1→2, git-auto-commit-action 4→5, fetch-metadata), a README update, and PHP 8.3 added to the test matrix. No formatter API changes, no config changes, no deprecations. Dropping it in from 2.0.0 is a low-risk composer update and buys you a verified PHP 8.3 signal rather than new behaviour.
• Extension point: if the shipped formatters don't match your CI's expected schema, PHP Insights accepts custom formatter classes — implement the formatter interface in your own app and reference it by class rather than forking this package.