Laravel Laravel Package

Getting Started

• Install with composer require --dev <vendor>/<package> and note the hard constraints in v1.9.0: Laravel ^13.33.0 and Boost ^2.10.0. If the app is still on Laravel 12.x or an older Boost, resolve that first — Composer will refuse the install rather than degrade gracefully.
• Look first at three places in the package: composer.json (scripts + constraints), the shipped rector.php / phpstan.neon config stubs, and .github/workflows/ (which shows exactly how the maintainers expect the tooling to be invoked).
• First use case: run the analysis pipeline once locally to confirm it works before wiring it into CI.

  vendor/bin/rector process --dry-run
  vendor/bin/phpstan analyse
  

• After upgrading to v1.9.0, expect the first run to be slow: caches moved from the system /tmp to the project's tmp/ folder, so every existing cache is effectively cold. Subsequent runs are fast again.

Implementation Patterns

• One entry point for local and CI. Add the two commands to composer.json scripts (composer refactor, composer analyse) and have the GitHub workflow call the same scripts. The package's own workflow uses actions/checkout@v7 and actions/cache@v6, which is the pattern to mirror in your app repo.
• Cache tmp/ in CI, not /tmp. With v1.9.0's project-relative caches, the actions/cache@v6 step must point at tmp/rector and tmp/phpstan (or tmp/ wholesale). Caching /tmp in a container job now caches nothing useful, and the cache key should include the PHP version plus the package version so a bump invalidates it.
• Fail on drift, fix locally. Run Rector with --dry-run in CI so a pull request fails if refactors are pending, and let developers apply them locally with the plain command. This keeps the apply step out of the pipeline and avoids bot commits.
• Upload reports as artifacts. The package's workflow uses actions/upload-artifact@v7; do the same with PHPStan's --error-format=json or a checkstyle/gitlab output so failures are inspectable without re-running the job.
• Keep a baseline under version control. Generate phpstan-baseline.neon at the project root and only extend it deliberately. After the dependency bump in v1.9.0, re-run analysis with the baseline disabled once to see what the newer Laravel/Boost stubs surfaced.
• Treat the configs as extension points. Copy the shipped rector.php and phpstan.neon into the project root and edit them there; register project-specific rule sets, paths, and excludes rather than forking the package.

Gotchas and Tips

• tmp/ must be gitignored, not deleted from CI. Add tmp/ to .gitignore but keep it in the workflow's cache path list. Committing the cache directory produces enormous, noisy diffs.
• The v1.9.0 cache move orphans old caches. Anything previously written to /tmp/rector or /tmp/phpstan is silently abandoned. That is harmless, but a slow first run after upgrading is expected — don't chase it as a performance regression.
• Read-only or ephemeral working directories break the new default. Containers, Nix sandboxes, and CI workspaces mounted read-only can't write to tmp/. Point the cache back to a writable location via the --cache-dir / tmpDir setting in the config rather than downgrading the package.
• Parallel jobs sharing a workspace collide. Two analysis jobs running in the same checkout will contend for tmp/. Give each job its own workspace or a distinct cache directory.
• GitHub Actions major bumps may not run everywhere. checkout@v7, cache@v6, and upload-artifact@v7 assume current runner images. Self-hosted runners on older actions/runner versions will fail at job startup — update the runner before adopting the workflow file.
• Bump dependencies with -W. Use composer update --with-all-dependencies when moving to Laravel ^13.33.0 / Boost ^2.10.0, otherwise transitive pins keep you on the old set and the new static-analysis stubs won't be picked up.
• Debugging false positives: re-run PHPStan with the baseline commented out and --debug; for Rector, narrow to a single path (vendor/bin/rector process app/Models --dry-run) before blaming a rule.
• Nothing in v1.9.0 is breaking. The release is cache location, CI action versions, and dependency floors. Existing pipelines keep working; the only required action is updating cache paths and runner versions.