README

Backward-compatible Rector rules for library maintainers.

Installation

Install as a development dependency:

composer require --dev art4/rector-bc-library

This package is intended to be used alongside Rector. If you don't already have Rector in the project, add it as a dev dependency too:

composer require --dev rector/rector

Usage

The easiest way to use this package is to import the prepared set into your project's rector.php:

<?php

use Rector\Config\RectorConfig;

return RectorConfig::configure()
    ->withPreparedSets(
        // NOTE: Deactivate the default prepared typeDeclaration set with `false`
        typeDeclaraion: false
    )
    // Instead import this package's set as replacement
    ->withSets([
        \Art4\RectorBcLibrary\Set::BC_TYPE_DECLARATION,
    ])
;

Gradual (level-based) adoption

If you'd like to increase type coverage gradually one level at a time (recommended), you can use the provided helper to apply a subset of rules for a given level. Do not use the ->withTypeCoverageLevel() method. For example:

<?php

use Rector\Config\RectorConfig;

return RectorConfig::configure()
    // NOTE: Do not use the withTypeCoverageLevel() method
    //->withTypeCoverageLevel(25)
    >withRules(\Art4\RectorBcLibrary\Set::withTypeCoverageLevel(25))
;

Start with a low level and raise it iteratively as you gain confidence and run your tests.

Motivation

When Rector adds or narrows type declarations automatically, it usually improves type safety — but it can also introduce breaking changes for downstream projects that extend or override your classes or methods.

This package wraps selected Rector rules and applies them more cautiously to reduce the risk of accidental API breakage for library consumers.

Who should use this

Library maintainers whose packages are consumed or extended by other projects ✅
Projects where public API compatibility matters

If you are working on an application (not a library) or you control both upstream and downstream code, the standard Rector rules are often sufficient.

How it works

Each wrapper inspects the code (for example: final/private status, vendor-lock signals, and other heuristics) before applying a change.
If the wrapper detects a potential risk to downstream compatibility, it skips the change; otherwise it delegates to the original Rector rule.
Use the prepared set by importing \Art4\RectorBcLibrary\Set::BC_TYPE_DECLARATION (see Usage).

Benefits ✅

Reduce the chance of unexpected breaking changes when modernizing code
Keep most of Rector's automated improvements while protecting public APIs
Low-friction: works with your current Rector setup

License

This project is licensed under the GNU General Public License v3 or later (GPL-3.0-or-later). See the LICENSE file for details.

Be sure your project's license is compatible with the GNU GPL v3+ before using this package.

Contributing

Thanks for considering contributing! The fastest way to help is:

Open an issue with a minimal reproducible example and the Rector version you used.
If possible, add a failing test or fixture that demonstrates the problem.
Run tests and static analysis locally: composer test and composer run phpstan.
Open a pull request with a clear description of the fix and why it's safe for library maintainers.

Contributions that include a test and a short explanation are especially appreciated — thanks! 🎉

art4 / rector-bc-library

Maintainers

Details