Phpstan Bodyscan Laravel Package

Getting Started

1. Install it as a dev-only dependency:

   composer require --dev tomasvotruba/phpstan-bodyscan
   

2. Make sure your Laravel project already has a working PHPStan setup. For Laravel, that usually means larastan/larastan plus a phpstan.neon/phpstan.neon.dist that includes app/, routes/, and any custom source directories.
3. Check the binary and available options:

   vendor/bin/phpstan-bodyscan --help
   

4. Start with a bounded scan rather than the whole repository:

   vendor/bin/phpstan-bodyscan app
   

   Then widen the scope once you know how long it takes and how noisy the report is.

The first practical use case is legacy triage: run the scan over one Laravel namespace, use the report to pick the next class or module to refactor, then re-run after the change to confirm progress. v0.2.0 is the first release worth using for CI because it adds --json output and raises the default memory limit for large projects.

Implementation Patterns

• Add repeatable Composer scripts so the team runs the same command:

  "scripts": {
      "scan": "phpstan-bodyscan app",
      "scan:json": "phpstan-bodyscan app --json > build/bodyscan.json"
  }
  

• Use the JSON output as a CI artifact, not just console output:

  vendor/bin/phpstan-bodyscan app --json > build/bodyscan.json
  

  Upload build/bodyscan.json from GitHub Actions/GitLab CI and compare counts or top offenders between branches.
• Keep PHPStan as the correctness gate and use this package as a prioritization/triage tool. A common workflow is: PHPStan fails the build on new errors; the body scan report tells you where the existing error mass is concentrated.
• For large Laravel apps, scan by domain/module first:

  vendor/bin/phpstan-bodyscan app/Domain/Billing
  vendor/bin/phpstan-bodyscan app/Domain/Orders
  

  This keeps memory bounded and gives teams ownership of their own reports.
• During a refactor, store a baseline JSON file and diff it:

  vendor/bin/phpstan-bodyscan app --json > build/before.json
  # refactor
  vendor/bin/phpstan-bodyscan app --json > build/after.json
  

  Use jq or a small script to compare totals and per-file counts.
• In Laravel-specific config, exclude generated and non-source paths: vendor/, storage/, bootstrap/cache/, public/build/, and any generated IDE helper files. Include only paths you actually maintain.
• Wrap the command in an Artisan command or CI script if you need team-specific thresholds, Slack summaries, or GitHub PR comments from the JSON output.

Gotchas and Tips

• This is still a 0.x package. Pin it (^0.2) and read the changelog before upgrading; CLI flags and JSON shape can change.
• --json is intended for machine consumption. Redirect stderr separately so progress/warning text does not corrupt the JSON:

  vendor/bin/phpstan-bodyscan app --json > build/bodyscan.json 2> build/bodyscan.err
  

  Validate with jq empty build/bodyscan.json in CI before parsing.
• v0.2.0 raises the memory limit, but a very large Laravel monorepo may still need an explicit override:

  php -d memory_limit=2G vendor/bin/phpstan-bodyscan app
  

  If memory is still an issue, split the scan by namespace.
• Laravel facades, helpers, and dynamic properties produce misleading PHPStan noise without Larastan. Install and configure larastan/larastan before trusting the scan output.
• Run composer dump-autoload after adding new namespaces or changing autoload config; stale autoloading can make the report incomplete.
• If results look stale after config changes, clear PHPStan’s result cache and re-run. Configuration changes are a common reason a scan appears not to reflect the current codebase.
• Do not deploy this as a production dependency. It belongs in require-dev and CI only.
• The main extension point is your PHPStan configuration: includes, excludePaths, analysis level, and custom rules all shape what the body scan reports. Use scoped phpstan.neon files when different Laravel modules need different rules.