Php Coding Standard Laravel Package

Getting Started

• Install as a dev-only dependency (composer require --dev …). This is a code-transformation tool — it should never ship to production and should not appear in require.
• Look first at two things: the README's set-list table (which rule sets exist and what each targets) and the package's own composer.json require / conflict block. The constraint block tells you which PHP, Laravel, and Pest versions you're actually allowed onto — that's what v1.1.0 changed.
• Minimal setup is a rector.php at the project root that imports the package's set list and points at source paths:

return RectorConfig::configure()
    ->withPaths([__DIR__ . '/app', __DIR__ . '/tests'])
    ->withSets([/* the package's set list(s) */]);

• First run is always a dry run: vendor/bin/rector process --dry-run on a clean git branch. Read the diff before you let it write anything.
• Best first use case: pick one narrow goal — a single directory (e.g. app/Http/Controllers) and a single rule set. Do not turn on every set on day one; the diff will be unreviewable and you'll lose confidence in the tool.

Implementation Patterns

• Opt-in Pest rules via env. The RECTOR_PEST switch is deliberately not on by default. Set it in CI or in a shell session only when you actually intend to run the Pest-conversion rules, and keep it out of the default developer config so day-to-day runs stay fast and low-noise.
• Two configs, not one. A root rector.php for app/ and a separate config for tests/ lets you apply aggressive rules to test code and conservative rules to domain code. Run them as two separate commands in CI.
• CI ratchet gate. A job that runs rector process --dry-run --no-progress-bar and fails on a non-empty diff keeps the codebase from drifting backwards. This is the highest-value integration: it turns the package from an occasional upgrade tool into a permanent invariant.
• Pipeline ordering. Rector → Pint → PHPStan → tests. Rector rewrites structure, so formatting and static analysis must run after it, or you'll be fixing violations that no longer exist.
• Prep-PR pattern for major upgrades. Run the relevant rule set against the current framework version, land the resulting PR (tests still green on the old version), then bump the framework/Pest constraint in a separate, tiny PR. This isolates "did the automated rewrite break something?" from "did the upgrade break something?".
• Scope aggressively in monorepos. Paths are resolved relative to the config file, so give each package/worktree its own config and run per-package rather than one giant root config.
• Escape hatches for legacy code. Use skip configuration / inline annotations for files you can't touch yet, then remove them one at a time. Track the skip list in the config so it's visible in review.
• Pin the version and commit the config. Transformation output changes between minor releases; a floating constraint means CI diffs appear with no code change.

Gotchas and Tips

• v1.1.0 breaking-ish change: pestphp/pest-plugin-rector is now optional. If your config or CI sets RECTOR_PEST=true, you must composer require --dev pestphp/pest-plugin-rector yourself — otherwise the Pest rules simply won't be available and you'll get a no-op or a missing-rule error rather than a helpful message.
• Flip side of the same change: the previous hard requirement could pin you to Pest 3 and block Laravel 12. If you were holding back an upgrade because of a Composer conflict, re-run composer update — but don't assume the Pest rules survived the update; verify.
• Never merge a Rector diff blind. These are AST-level rewrites: comments can be dropped, imports reordered, visibility or type declarations altered, and custom base classes bypassed. Skim every file, or at minimum every file that isn't a pure import/namespace change.
• Stale cache. If results look wrong after a Composer or PHP bump, run with --clear-cache before debugging anything else.
• Rule ordering bites. Chained rules can produce output that a later rule then mangles. If the diff looks nonsensical, split the run into two invocations with narrower sets and compare.
• Keep Pest conversion in its own PR. It rewrites tests/ heavily; isolating it means a red test suite is unambiguously attributable to the conversion.
• Debugging: use -vvv to see which rule produced each hunk, and --dry-run --output-format=json if you want to feed results into a dashboard or script.
• Extension point: custom rules are the clean way to encode house conventions (your base TestCase, your DTO/action patterns). Register them alongside the package's sets rather than forking the package.
• Pest 4 / Laravel 12 support is now possible but not automatic — the release removes the blocker; it doesn't test your app for you. Run the full suite on the new matrix before assuming parity.