Extension Installer Laravel Package

Getting Started

rector/extension-installer is a Composer plugin that removes the need to hand-edit rector.php every time you install a Rector ruleset package. Extension packages tag themselves as rector-extension, and the plugin generates a config file that Rector loads automatically.

Minimum setup (consumer side):

1. Require the plugin as a dev dependency:

   composer require --dev rector/extension-installer
   

2. Allow the plugin. With Composer 2.2+ this is mandatory, otherwise the plugin is silently skipped:

   {
     "config": {
       "allow-plugins": {
         "rector/extension-installer": true
       }
     }
   }
   

3. Install any package that ships Rector rules and declares itself as an extension, then regenerate:

   composer require --dev <vendor>/<rector-extension>
   composer dump-autoload
   

Where to look first:

• vendor/rector/extension-installer/ — the plugin itself and the generated config file it writes (typically src/GeneratedConfig.php; confirm the exact path for your installed version).
• vendor/composer/installed.json — look at each package's type and extra keys to confirm which extensions the plugin will discover.
• Your project rector.php — confirm the generated file is actually being imported, and that you are not also hand-importing the same extension (double rules).

First use case: you have a rector.php with three manual $rectorConfig->import(...) lines for ruleset packages. Replace those with the plugin, run vendor/bin/rector process --dry-run, and verify the active rule list is unchanged. If it matches, you have a working baseline and can add future extensions with composer require alone.

Implementation Patterns

Consumer pattern — "install and forget". Treat the plugin as infrastructure: install it once, commit the allow-plugins entry, and never touch rector.php when onboarding a new ruleset. Keep rector.php for project-local configuration (paths, sets, skips) only.

Extension author pattern. If you publish a Rector ruleset, declare it so the plugin can find it:

{
    "type": "rector-extension",
    "extra": {
        "rector": {
            "includes": ["config/rector-rules.php"]
        }
    }
}

The config file should be a plain Rector config fragment (imports/rule registrations), not a full standalone rector.php, so it composes cleanly inside the host project.

CI / Docker pattern. The generated file lives in vendor/, so it is rebuilt on every clean install. Ensure CI runs a normal composer install (not --no-scripts / --no-plugins) with allow-plugins configured, then vendor/bin/rector process --dry-run. A stale or absent generated file is a common "works locally, fails in CI" cause.

Verification pattern. After adding an extension, assert the generated file references it and that the expected rule classes appear:

composer dump-autoload -v            # watch the plugin output
grep -R "<vendor>/<package>" vendor/rector/extension-installer/
vendor/bin/rector process --dry-run --debug

Migration pattern. When moving off the plugin, copy the generated import/require lines from the generated config into rector.php once, then remove the plugin. This keeps behaviour identical and avoids the generated-file dependency.

Gotchas and Tips

• Silent no-op without allow-plugins. The plugin simply does not run and extensions appear "not installed" to Rector. First debugging step is always composer diagnose plus a -v dump-autoload to confirm the plugin executed.
• Stale generation. The file is regenerated on Composer's post-autoload-dump. Adding an extension without a subsequent composer dump-autoload (or install/update) leaves Rector using the old rule list. If in doubt, dump and re-run.
• It is unmaintained (last release 2021). Verify compatibility with your Rector major version before relying on it. Rector's configuration API changed significantly around the RectorConfig class and withSets()/withRules(); a 2021-era generated-config mechanism may not be loaded by modern Rector at all. Read the generated file and the Rector binary's config loading to confirm the include actually happens — do not assume.
• Vendor-only artifact. The generated file is gitignored by convention. Never reference it from committed source, and never assume it exists in a --no-dev production deploy. If you run Rector outside dev, move the plugin to require.
• Duplicate rules. If both the plugin and your rector.php import the same extension, rules can be registered twice. Usually harmless for idempotent rules, but it bloats --debug output and can cause surprising ordering. Audit rector.php when adopting the plugin.
• Ordering. Discovery order is effectively package-name driven, not the order you required packages. If two extensions override the same rule, the winner is not obvious — pin ordering by importing the conflicting extension manually in rector.php and removing it from the auto-discovery path.
• Package type is the whole contract. A package that ships Rector config but is not typed rector-extension (or lacks the extra.rector.includes entry) will be ignored without warning. Check composer show <package> and the package's composer.json.
• Extension point for tooling. The plugin is a small Composer plugin; if you need filtering (e.g., only register extensions matching an env), fork it and gate on an env var in the plugin's discovery logic rather than patching generated files.
• License is NOASSERTION. For commercial use, confirm terms from the source repository before depending on it; do not rely solely on the package metadata.
• Low adoption (0 dependents). Budget time for abandonment: the safest long-term posture is manual import() lines in rector.php, using the plugin only if your extension list is large and churny.