Rector Generator Laravel Package

Getting Started

Deprecation notice: rector/rector-generator lives under the deprecated-packages org and is archived. The rule-scaffolding workflow it pioneered was folded into Rector core as the generate command. If you are on a modern Rector (1.x), skip this package and run vendor/bin/rector generate from rector/rector directly. Reach for rector-generator only if you are pinned to an older Rector that predates the built-in command.

Minimal steps to get a working scaffold:

1. Install as a dev dependency (never in production): composer require --dev rector/rector-generator.
2. Make sure a rector.php config exists at project root – the generator reads paths/namespaces from it and from composer.json autoloading.
3. Run the interactive generator: vendor/bin/rector generate (older builds may expose it as a standalone binary; check vendor/bin/ and the README for your pinned version).
4. Answer the prompts: rule type (e.g. method call, class, property), the node/class it targets, the intended change, and the namespace/paths where the rule and its test should live.

The command produces a triplet you will live in every time you write a rule:

• rules/.../YourRector.php – the Rector rule skeleton.
• rules-tests/.../YourRector/YourRectorTest.php – a PHPUnit test extending AbstractRectorTestCase.
• rules-tests/.../YourRector/Fixture/*.php.inc – input/expected fixture pair.

First use case: scaffold a rule that rewrites a legacy helper call (old_helper()) into a new API (NewHelper::run()), then fill in getRuleDefinition(), getNodeTypes() and refactor(). Run vendor/bin/rector process path/to/fixture --dry-run to watch it rewrite. The generated test is your regression harness from the very first commit.

Implementation Patterns

Fixture-first loop. Write the input fixture by hand (the code you want changed), scaffold the rule, then implement refactor() until vendor/bin/rector process ... --dry-run emits the expected output. Copy the diff into the expected file and lock it in with vendor/bin/phpunit rules-tests/.../YourRectorTest.php.

One rule, one node type. getNodeTypes() should return the narrowest node class that can express your change (MethodCall, ClassMethod, PropertyFetch). The generator's skeleton often defaults to a broader node – tighten it immediately so Rector's traversal doesn't invoke your rule on unrelated AST nodes.

Keep getRuleDefinition() honest. The code sample in getRuleDefinition() is rendered in Rector's docs and error messages. Stale samples are the most common review comment on generated rules; update them whenever refactor() semantics change.

Registration in rector.php. The generator usually appends the new rule to withRules([...]), but verify. During development you can also register the single rule inline and scope it with withPaths() to keep iteration fast instead of running the whole ruleset.

Test harness contract. The generated test almost always boils down to:

protected function provideConfigFilePath(): string
{
    return __DIR__ . '/config/configured_rule.php';
}

That config file must instantiate the rule. If the generator did not create it, create it – a missing config is the usual reason a freshly generated test reports "0 assertions".

Batch scaffolding. When migrating a large codebase, you will write many small, near-identical rules (e.g. one per deprecated method). Generate the first one, then copy the triplet and adjust the prompts' outputs rather than re-running the interactive command dozens of times. This preserves your project's exact naming and path conventions.

CI integration. Add a job that runs vendor/bin/phpunit rules-tests alongside vendor/bin/rector process --dry-run on the repo itself. Generated rules that rewrite your own code are cheap to validate and catch regressions early.

Gotchas and Tips

• Version compatibility is the big one. rector-generator targets older Rector internals (AbstractRector, RectorRecipe, older node-type contracts). Pinning Rector to a matching minor is essential; a Composer update can break the generator and the rules it produced. Prefer core rector generate wherever possible.
• Autoloading of fixtures. Fixtures are not PSR-4 classes in the usual sense. If your fixture references project classes, register the relevant paths via RectorConfig->withAutoloadPaths() or the test will fail with "class not found" rather than a rule error.
• Fixture naming matters. The test convention expects input/expected file pairs (often with a .php.inc extension) under a Fixture/ directory. Renaming a file without updating the test silently drops coverage.
• Cache masking changes. Rector caches parsed files. After editing a rule, a stale result can look like your change did nothing. Run vendor/bin/rector clear-cache (or --clear-cache) before concluding the rule is broken.
• --dry-run plus -v. --dry-run shows the would-be diff; -v/-vv prints the node traversal details that tell you whether refactor() was even entered.
• Node replacement vs. mutation. refactor() can return a new node, an array of nodes, or null. Returning null from a branch silently means "no change" – a frequent cause of "my rule does nothing" reports. Be explicit about which contract you are using for your Rector version.
• Don't touch files you didn't match. Guard refactor() with $node instanceof ... even when getNodeTypes() is narrow; subclasses and dynamic calls can surprise you.
• Extension point: if the CLI prompts don't fit your project's layout, the package's recipe/config object is the seam to override – but on a deprecated package, treating that seam as stable is risky. Copy the scaffold into your own tools/ script instead and freeze the template.
• Upgrade path. The moment you can move to Rector 1.x, delete this package: the built-in generator covers the same workflow, stays in sync with the AST API, and removes the pinning problem from your composer.json.