Proposal: Support Composer extra.rector metadata for package-level config auto-discovery

[peterfox]

It would be useful if Rector could automatically load configuration files provided by third-party packages (e.g. framework-specific rule sets such as Laravel Rector).

This avoids each user needing to manually import configs in their own rector.php, and allows packages to self-register additional rules or settings in a clean, Composer-native way.

Motivation

Many ecosystem packages ship additional Rector rules, sets, or configuration. Right now each user must manually add:

$config->import(__DIR__ . '/vendor/vendor-name/package/rector.php');

This is an extra step for things like rules that rely on NodeVisitors that silently fail when a set of NodeVisitors haven't been used.

Composer already supports the extra section for package-specific metadata.

Proposed solution

1. Packages declare a config file via composer.json

Example for a package providing Rector rules:

{
  "extra": {
    "rector": {
      "config": "rector.php"
    }
  }
}

This path would be relative to the package root, e.g.:

vendor/vendor-name/package/rector.php

The package can expose any number of rules or configuration inside that file.

2. Rector automatically imports these configs

During config loading, Rector would:
1. Read vendor/composer/installed.json
2. Look for packages containing "extra.rector.config"
3. Import the referenced file before applying the user’s own rector.php

Pseudo-implementation:

$installed = json_decode(file_get_contents(__DIR__ . '/vendor/composer/installed.json'), true);

foreach ($installed['packages'] as $pkg) {
    $configPath = $pkg['extra']['rector']['config'] ?? null;

    if ($configPath) {
        $absolute = __DIR__ . '/vendor/' . $pkg['name'] . '/' . $configPath;
        if (is_file($absolute)) {
            $config->import($absolute);
        }
    }
}

This provides a deterministic, explicit discovery mechanism without the downsides of Composer plugins or runtime directory scanning.

Benefits
• Zero-setup for end users installing rule-set packages
• Explicit and stable — discovery controlled entirely via composer.json
• Plays well with existing Rector config structure

Backwards compatibility
• No breaking changes
• Auto-discovery can be enabled by default or behind a small toggle
• Users can still manually import files as usual

Example use case

Laravel Rector could ship:

composer.json
rector-laravel.php

{
  "extra": {
    "rector": {
      "config": "rector-laravel.php"
    }
  }
}

On install, Rector would automatically load the Laravel-specific rules with no extra work required by the user.

[TomasVotruba]

Thanks for proposal.
Looks TLDR and GPT generated. Mind the dash 😅

How is it superior to SetProviders? They handle config autoloading.

[peterfox]

Won't lie, I used ChatGPT to put it together 😅

These reason for the proposed idea is this PR driftingly/rector-laravel#444

Since NodeVisitors are the best way to do things, we need a default config to apply them. Problem is with set providers, people would still need to specify in the config they're using Laravel Rector. Where as with this they could install a package an automatically have the benefits of the NodeVisitors.

[TomasVotruba]

If issue/PR description is longer than 10 lines, it's always GPT 😅

What does the rule so in a gist that cannot be handled with core attributes?
Might be worth adding to core.

[peterfox]

There's a couple rules but let's just look at ServerVariableToRequestFacadeRector.

it needs to convert ArrayDimFetch to a Static Method call. But the problem is only read access with the ArrayDimFetch can be used, so we need to check it's not used for assignment or used with things like isset or unset otherwise it would break the code. We can do the checks within a rule but it becomes quite messy and hard to understand the rule when a NodeVisitor makes more sense.

It would simply be good to be able to register services to the container without having to tell end users to import a config or use a Config object to wrap around the main rector one.

[TomasVotruba]

I see :)

The rule is listed in: https://github.com/driftingly/rector-laravel/blob/901d5191a662f99e09b2bb9b3da75047ba4e8ff8/config/sets/laravel-code-quality.php#L42

Is there a use case someone would copy-paste this rule as standalone outside this set? If not, register the visitor there and you're done 👍

It should be used as a part of the set, then used as follows:

    ->withSets([
        LaravelSetList::CODE_QUALITY
    ])

The reason I want to promote sets over rules is that most people use 5-15 sets all over again and don't want to go in a detail and copy paste class names back and forth (prone to bugs, easy to miss new rules and generally annoying work :))

[peterfox]

We can do that. Just personally, I still often use single rules on a codebase. I don't think the incremental steps will work for a third party package set, will it?

I just have a feeling it will lead to issues being generated later on when the rules are used an no attributes are found to stop bugs.

It would be great to have a way for rules to declare what node visitors are required.