Rector Src Laravel Package

Getting Started

First, decide which repository you actually need. rectorphp/rector-src is the development monorepo for Rector — it holds the rule implementations, the core engine, the test harness, and the build scripts that generate the distribution package. For 95% of day-to-day work you want the distribution:

composer require rector/rector --dev
vendor/bin/rector init          # writes rector.php
vendor/bin/rector process src --dry-run

Reach for rector-src only when you are (a) writing a custom rule and want to copy proven patterns, (b) debugging why a specific rule behaves oddly by reading its source, (c) contributing a rule upstream, or (d) reproducing a bug against unreleased main.

Cloning the source repo:

git clone https://github.com/rectorphp/rector-src
cd rector-src
composer install
vendor/bin/phpunit rules/DeadCode/tests/Rector/... # single rule
composer tests                                    # full suite

Where to look first, in order:

1. src/Rector/AbstractRector.php — the contract every rule implements (getNodeTypes(), refactor(), getRuleDefinition()).
2. rules/<Category>/Rector/<RuleName>.php — the largest corpus of real-world examples anywhere. If you want to know how to rewrite a node, a rule almost certainly already does it.
3. rules/<Category>/tests/Rector/<RuleName>/ — the fixture + config layout you should mirror for your own rules.
4. rector.php at the repo root — the project's own self-application config, a good template.

First use case: run Rector on your own codebase with a narrow set (e.g. ->withSets([LevelSetList::UP_TO_PHP_82])) in --dry-run, review the diff, then apply. That gives you an immediate sense of the rule surface before you write anything custom.

Implementation Patterns

Config-first, sets before rules. RectorConfig::configure()->withPaths([__DIR__.'/src'])->withSets([...])->withRules([...]) is the canonical shape. Prefer set lists for framework/PHP upgrades and withRules() for surgical, single-purpose rewrites. Keep one rector.php per scope (app vs. tests vs. legacy) rather than one giant config with heavy withSkip() logic.

Writing a custom rule (the most common reason to open rector-src):

final class MyRule extends AbstractRector
{
    public function getRuleDefinition(): RuleDefinition { /* docs + code sample */ }
    public function getNodeTypes(): array { return [MethodCall::class]; }
    public function refactor(Node $node): ?Node { /* return null = no change */ }
}

Then register it in rector.php via ->withRules([MyRule::class]) and make sure the class is autoloadable from the config's directory (Rector autoloads the directory containing rector.php, so a utils/Rector/ folder next to it works without extra Composer wiring).

Testing pattern — copy it verbatim. Extend AbstractRectorTestCase, implement provideConfigFilePath() pointing at a fixture config, and put input/expected output in the same fixture file separated by -----. Add @dataProvider provideData() returning __DIR__ . '/Fixture/*.php.inc'. This is exactly how every rule in rules/ is tested; deviating from it will cost you hours.

Two-pass workflow with PostRector. If your rule needs to run after printing/import resolution (adding use statements, cleaning imports), study packages/PostRector instead of trying to do it inside a normal rule. Ordering bugs here are subtle and the only reliable fix is using the right phase.

CI integration. vendor/bin/rector process --dry-run --no-progress-bar returns non-zero on pending changes — wire it as a gate alongside PHPStan/CS. Run it on changed paths only (rector process $(git diff --name-only origin/main... | grep '\.php$')) to keep PR pipelines fast.

Debugging a rule you don't understand: run with --debug/-vvv for node-by-node output, and drop an exit or dump() into refactor() inside a vendor-patched copy if needed. For source-level work, the rules/*/tests fixtures double as executable documentation — search the fixtures for the node type you care about.

Gotchas and Tips

Do not composer require rector/rector-src in a project. It is the unprefixed dev monorepo: it pulls PHPUnit/PHPStan/dev tooling, has no dependency scoping, and its tags are not intended as consumable releases. The distribution repo exists precisely because the prefixed build is what end users can safely install. rector-src also lags/leads the distribution depending on release cadence, so a rule documented on main may not exist in your installed version — always check the rule exists in your vendor/bin/rector version before writing config.

Cache confusion is the #1 false-negative. Rector caches results (default under the system temp dir). If a rule "stops working" after you edit it, run --clear-cache. When editing a custom rule, the cache key may not change, so clear it every iteration.

--dry-run alone hides the diff. Add --output-format=json for machine consumption or rely on the default diff view in a TTY; in CI the plain text diff is often truncated.

Rule ordering and idempotency. Rules run in a fixed, non-obvious order and the engine loops until stable. Non-idempotent rules (e.g. one that appends to an array every pass) will loop or produce garbage. Always verify your rule is a no-op when re-run on its own output.

Skip semantics are pattern-based. withSkip() accepts rule class strings and fnmatch path patterns; a path pattern that looks like it should match often doesn't (*/Tests/* vs *Tests*). Verify by running with -vvv and confirming the file is listed. Attribute/annotation-based skipping exists for one-off opt-outs inside code — check src/ for the current attribute class name, since it has moved between namespaces across majors.

Docs are generated, not hand-written. docs/rector_rules_overview.md is produced from getRuleDefinition(). Manually editing it in a PR gets overwritten by the docs build script — change the rule definition instead. Same for rule registration in set lists: those arrays are ordered and generated/validated, so adding an entry in the wrong position silently changes upgrade behavior.

Fixture whitespace is significant. The ----- separator block must end exactly where expected; a missing trailing newline is the most common cause of a baffling fixture failure. composer fix-cs/the repo's own Rector run will also reformat fixtures if you're not careful.

Parallel runs and memory. --parallel speeds up large codebases but interacts badly with Xdebug (disable it) and with very large single files. The monorepo's own test suite needs generous memory_limit — if composer tests OOMs, raise it before assuming a broken install.

Extension points to prefer over patching core: custom rules, PostRector implementations, RectorConfig fluent options, and the AbstractRectorTestCase harness. Forking src/ internals gives you a merge conflict on every release; the stable seams are the rule contract and the config object.