rector/rector

rector/rector is a powerful and open-source PHP tool designed for automated refactoring and instant upgrades of PHP applications. It's often referred to as a "refactoring bot" or a "tool for instant upgrades" because its primary purpose is to analyze existing PHP code, identify outdated patterns, deprecated syntax, and opportunities for modernization, and then automatically apply the necessary changes.

Purpose and Functionality:
Rector operates by parsing PHP code into an Abstract Syntax Tree (AST), applying a series of predefined "rules" or "sets" of rules, and then printing the modified AST back into PHP code. This AST manipulation allows Rector to perform complex code transformations that would be tedious and error-prone to do manually.

Key Use Cases:
1. PHP Version Upgrades: Rector can automate the upgrade process between different PHP versions (e.g., from PHP 7.4 to 8.0, 8.1, 8.2, or even 8.3), handling syntax changes, new features, and deprecated functionalities.
2. Framework Upgrades: It provides rulesets for popular PHP frameworks like Symfony, Laravel, Nette, and Doctrine, helping developers upgrade their applications to newer versions of these frameworks.
3. Dependency Upgrades: Rector can assist in upgrading other PHP libraries and dependencies by applying changes required by their new versions.
4. Code Modernization: It can introduce modern PHP features (e.g., short array syntax, null coalesce operator, typed properties, named arguments) to older codebases.
5. Deprecation Removal: Automatically replaces deprecated functions, classes, or methods with their modern equivalents.
6. Code Style and Best Practices: While not its primary focus (like PHP_CodeSniffer or PHP-CS-Fixer), Rector can also apply certain code style improvements and enforce best practices.

How it Works:
1. Configuration (`rector.php`): Users define which rules or rule sets Rector should apply in a `rector.php` configuration file. These rules are specific transformations.
2. Analysis: Rector scans the specified directories or files, parses them into an AST.
3. Rule Application: It then iterates through the AST, applying the enabled rules. Each rule looks for specific patterns in the AST and modifies them according to its logic.
4. Code Generation: Finally, Rector converts the modified AST back into PHP code, effectively refactoring the files in place.

Benefits:
* Time-Saving: Dramatically reduces the manual effort and time required for large-scale refactoring and upgrades.
* Consistency: Ensures changes are applied consistently across the entire codebase.
* Reduced Errors: Minimizes human error associated with manual refactoring.
* Faster Adoption of New Features: Helps projects stay current with the latest PHP versions and framework releases.
* Easier Code Maintenance: Modernized code is generally easier to maintain and understand.

```php
// 1. rector.php (Rector Configuration File)
// This file specifies which rules Rector should apply.
// For this example, we'll use a PHPUnit ruleset to fix deprecated assertions.

use Rector\Config\RectorConfig;
use Rector\PHPUnit\Set\PHPUnitSetList;

return function (RectorConfig $rectorConfig): void {
    // Define the paths where Rector should look for PHP files to refactor
    $rectorConfig->paths([
        __DIR__ . '/src',
        __DIR__ . '/tests',
    ]);

    // Import sets of rules for common upgrade scenarios.
    // Here, we use a set for PHPUnit 9.0 upgrades, which includes rules
    // to replace deprecated assertions like assertNotContains for strings.
    $rectorConfig->sets([
        PHPUnitSetList::PHPUNIT_90,
    ]);

    // You can also add individual rules if a specific transformation is needed
    // $rectorConfig->rule(YourCustomRule::class);
};

// 2. tests/ExampleTest.php (Original Code Before Rector)
// This file contains a PHPUnit test with a deprecated assertion method.

namespace App\Tests;

use PHPUnit\Framework\TestCase;

class ExampleTest extends TestCase
{
    public function testStringContains(): void
    {
        // assertNotContains is deprecated for checking string presence in PHPUnit 9+
        // It should be replaced with assertStringNotContainsString for string arguments.
        $this->assertNotContains('foo', 'foobar', 'Message: "foo" should not be in "foobar"');
    }
}

// To run Rector, you would typically use a command like:
// vendor/bin/rector process tests --dry-run (to see changes without applying)
// vendor/bin/rector process tests (to apply changes)

// 3. tests/ExampleTest.php (Code After Rector Runs)
// Rector, using PHPUnitSetList::PHPUNIT_90, automatically updates the deprecated assertion.

namespace App\Tests;

use PHPUnit\Framework\TestCase;

class ExampleTest extends TestCase
{
    public function testStringContains(): void
    {
        // Rector has automatically refactored the method to its modern equivalent.
        $this->assertStringNotContainsString('foo', 'foobar', 'Message: "foo" should not be in "foobar"');
    }
}
```