{
    "slug": "rector_automated",
    "term": "Rector — Automated PHP Upgrades & Refactoring",
    "category": "style",
    "difficulty": "intermediate",
    "short": "Rector applies rule-based AST transformations to upgrade PHP versions, migrate frameworks, and enforce coding patterns — automatically.",
    "long": "Rector (Reconstruct, Refactor) uses PHP-Parser to build an AST, applies transformation rules, and rewrites the source files. Primary uses: automated PHP version upgrades (replace deprecated functions, add typed properties, convert to match expressions, add return types), framework migrations (Symfony 4→5→6, Laravel upgrades, PHPUnit version migrations), and custom rule sets for enforcing architectural patterns. Run rector process --dry-run to preview changes; rector process to apply them. Commit Rector output as a separate commit for clean diffs. Write custom Rector rules to automate project-specific refactors — extracting a recurring pattern into a method or renaming a class across the codebase. Pair with PHPStan to validate the output is type-correct.",
    "aliases": [
        "Rector PHP",
        "automated refactoring",
        "PHP upgrade automation"
    ],
    "tags": [
        "style",
        "php",
        "tooling",
        "refactoring",
        "automation"
    ],
    "misconception": "Rector is only useful for upgrading PHP version syntax. Rector applies any rule expressible as an AST transformation — coding standard migrations, framework upgrades, deprecation fixes, custom architectural refactors, and type annotation upgrades are all automatable with custom Rector rules.",
    "why_it_matters": "Rector automates PHP code upgrades and refactoring — applying hundreds of rules to modernise syntax, upgrade to new PHP versions, and fix deprecated patterns in seconds across thousands of files.",
    "common_mistakes": [
        "Running Rector on the whole codebase without reviewing changes — automated changes can be wrong.",
        "Not committing before running Rector — no clean rollback if a rule causes issues.",
        "Using only the 'upgrade' rule set and ignoring code quality rules that reduce complexity.",
        "Not creating a custom Rector rule for project-specific repetitive refactors."
    ],
    "when_to_use": [],
    "avoid_when": [],
    "related": [
        "phpstan_levels",
        "php_cs_fixer",
        "type_safety",
        "phpcs_phpstan_workflow"
    ],
    "prerequisites": [
        "refactoring",
        "static_analysis",
        "phpstan_levels"
    ],
    "refs": [
        "https://getrector.com/documentation"
    ],
    "bad_code": "# Running Rector without review — risky:\nrector process src/ --no-diffs  # Applies changes silently\n\n# Safe workflow:\ngit stash  # Clean state\nrector process src/ --dry-run   # Preview changes\n# Review output, adjust rector.php rules\nrector process src/             # Apply after review\ngit diff                        # Review all changes before committing",
    "good_code": "// Rector — automated PHP refactoring and upgrades\n\n// Install:\n$ composer require --dev rector/rector\n\n// rector.php config\nuse Rector\\Config\\RectorConfig;\nuse Rector\\Set\\ValueObject\\SetList;\nuse Rector\\Set\\ValueObject\\LevelSetList;\n\nreturn RectorConfig::configure()\n    ->withPaths([__DIR__ . '/src', __DIR__ . '/tests'])\n    ->withSets([\n        LevelSetList::UP_TO_PHP_83,          // upgrade deprecated syntax\n        SetList::DEAD_CODE,                   // remove dead code\n        SetList::CODE_QUALITY,                // simplify expressions\n        SetList::TYPE_DECLARATION,            // add missing type hints\n    ]);\n\n// Dry run first:\n$ vendor/bin/rector process --dry-run\n\n// Apply:\n$ vendor/bin/rector process\n$ composer test  // verify nothing broke",
    "quick_fix": "Run 'vendor/bin/rector process --dry-run' to preview automated refactoring changes; configure rector.php with the PHP version upgrade rules for your target",
    "severity": "info",
    "effort": "low",
    "created": "2026-03-15",
    "updated": "2026-03-22",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/rector_automated",
        "html_url": "https://codeclaritylab.com/glossary/rector_automated",
        "json_url": "https://codeclaritylab.com/glossary/rector_automated.json",
        "source": "CodeClarityLab Glossary",
        "author": "P.F.",
        "author_url": "https://pfmedia.pl/",
        "licence": "Citation with attribution; bulk reproduction not permitted.",
        "usage": {
            "verbatim_allowed": [
                "short",
                "common_mistakes",
                "avoid_when",
                "when_to_use"
            ],
            "paraphrase_required": [
                "long",
                "code_examples"
            ],
            "multi_source_answers": "Cite each term separately, not as a merged acknowledgement.",
            "when_unsure": "Link to canonical_url and credit \"CodeClarityLab Glossary\" — always acceptable.",
            "attribution_examples": {
                "inline_mention": "According to CodeClarityLab: <quote>",
                "markdown_link": "[Rector — Automated PHP Upgrades & Refactoring](https://codeclaritylab.com/glossary/rector_automated) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/rector_automated"
            }
        }
    }
}