Phpstan Baseline Per Identifier Laravel Package

Getting Started

Start by installing the package and configuring the new baseline structure. First, run:

composer require --dev shipmonk/phpstan-baseline-per-identifier

Then remove your existing single baseline include from phpstan.neon.dist (e.g., includes: - phpstan-baseline.neon), and set up the loader-based workflow:

1. Generate a temporary single-file baseline with --generate-baseline=baselines/_loader.neon
2. Run vendor/bin/split-phpstan-baseline baselines/_loader.neon to split it
3. Ensure includes: - baselines/_loader.neon is in your PHPStan config

This instantly enables per-error baseline files (e.g., baselines/empty.notAllowed.neon) for easier review and management.

Implementation Patterns

• Use Composer scripts for automation
  Define scripts like:

  {
      "scripts": {
          "phpstan:baseline": [
              "phpstan --generate-baseline=baselines/_loader.neon",
              "split-phpstan-baseline baselines/_loader.neon"
          ],
          "phpstan:baseline:update": [
              "phpstan analyse --error-format=raw",
              "@phpstan:baseline"
          ]
      }
  }
  

  This makes baseline regeneration part of CI/CD and PR workflows.

• Leverage PHP baselines for consistency
  If your project already uses baseline.php, switch to baselines/loader.php — the same splitting logic applies, and it integrates with PHPStan’s result cache.

• Integrate with CI
  In CI, run phpstan analyse without regeneration, then fail only on new errors (since baselines are pre-split and versioned). Use --error-format=raw for human-readable logs.

• Team workflow
  Developers can inspect/modify specific error types (e.g., foreach.nonIterable.neon) in small diffs, reducing merge conflicts and improving review focus.

Gotchas and Tips

• Cache invalidation pitfall
  PHP baselines require .php extension for cache to work correctly — don’t accidentally name it _loader.neon if you want PHP output. Double-check the loader file extension determines the generated file format.

• Preserved error order = cleaner diffs (v2.3+)
  Since 2.3.0, regenerating baselines preserves the original order of existing errors and only inserts new ones at sorted positions — no need for manual sorting or sort scripts. Rely on this for predictable diffs.

• Orphaned file cleanup
  The split-phpstan-baseline command auto-deletes baseline files that no longer have errors — remove any old find baselines -name "*.neon" -delete scripts.

• CLI options for cleaner baselines
  Use --no-error-count if your team prefers uncluttered files (e.g., for compliance), or --tabs for consistency with your repo’s formatting.

• Legacy vs modern workflow
  If you see --error-format baselinePerIdentifier in old scripts, replace it with --generate-baseline + split-phpstan-baseline. The legacy method cannot use result cache and lacks rawMessage support.

• Check loader includes total count (v2.1.5+)
  The loader file now includes the total error count in its header comment — useful for verifying completeness after splits.