agentleFS
peterfoxpeterfox/agent-skills/rector-developer/SKILL.md

rector-developer

Skill25 starsChanged 9 months agoMITView on GitHub

Build Rector PHP rules that transform PHP code via AST. Use when asked to create, modify, or explain Rector rules for PHP code transformations. Rector rules use the PHP-Parser AST and PHPStan type analysis. Triggers on requests like "write a Rector rule to...", "create a Rector rule that...", "add a Rector rule for...", or when working in a rector-src or rector-based project and asked to implement code transformation logic.

The file

We split this skill into the rules it gives an agent

10 rules. About 0 are common, 1 is distinctive, and 9 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 9

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Write the rule class extending AbstractRector

    line 14
  2. Very specific:

    If PHP version gated, implement MinPhpVersionInterface

    line 15
  3. Very specific:

    If configurable, implement ConfigurableRectorInterface

    line 16
  4. Very specific:

    Always use Node\Name\FullyQualified for class references in AST nodes — never Node\Name.

    line 109
  5. Distinctive:

    Before transforming a class or its members, consider whether the change is safe in an inheritance context.

    line 119
  6. Very specific:

    If the class being transformed is not final, it may be extended.

    line 123
  7. Very specific:

    If yes and the risk is real, guard with isFinal() and skip non-final classes.

    line 127
  8. Very specific:

    If the rule is intentionally broad and the risk is accepted, document that reasoning in the rule's getRuleDefinition() description.

    line 128
  9. Very specific:

    Every rule needs a test class extending AbstractRectorTestCase with fixtures in a Fixture/ directory and a config in …

    line 242
  10. Very specific:

    Fixture tip: Write only the input section, run the test, and FixtureFileUpdater fills the expected output automatically.

    line 244

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Rector PHP Rule Builder

Rector transforms PHP code by traversing the PHP-Parser AST, matching node types, and returning modified nodes from refactor().

Workflow

  1. Check for an existing configurable rule first — see references/configurable-rules.md. Renaming functions/methods/classes, converting call types, and removing arguments are all covered. Prefer ->withConfiguredRule() over writing a custom rule for these cases.
  2. Identify the PHP-Parser node type(s) to target (see references/node-types.md)
  3. Write the rule class extending AbstractRector
  4. If PHP version gated, implement MinPhpVersionInterface
  5. If configurable, implement ConfigurableRectorInterface
  6. Register the rule in rector.php config

Rule Skeleton

<?php

declare(strict_types=1);

namespace Rector\[Category]\Rector\[NodeType];

use PhpParser\Node;
use PhpParser\Node\Expr\FuncCall; // target node type
use Rector\Rector\AbstractRector;
use Symplify\RuleDocGenerator\ValueObject\CodeSample\CodeSample;
use Symplify\RuleDocGenerator\ValueObject\RuleDefinition;

/**
 * @see \Rector\Tests\[Category]\Rector\[NodeType]\[RuleName]\[RuleName]Test
 */
final class [RuleName]Rector extends AbstractRector
{
    public function getRuleDefinition(): RuleDefinition
    {
        return new RuleDefinition('[Description]', [
            new CodeSample(
                <<<'CODE_SAMPLE'
// before
CODE_SAMPLE
                ,
                <<<'CODE_SAMPLE'
// after
CODE_SAMPLE
            ),
        ]);
    }

    /** @return array<class-string<Node>> */
    public function getNodeTypes(): array
    {
        return [FuncCall::class];
    }

    /** @param FuncCall $node */
    public function refactor(Node $node): ?Node
    {
        if (! $this->isName($node, 'target_function')) {
            return null;
        }

        // transform and return modified $node, or return null for no change
        return $node;
    }
}

refactor() Return Values

ReturnEffect
nullNo change, continue traversal
$node (modified)Replace with modified node
Node[] (non-empty)Replace with multiple nodes
NodeVisitor::REMOVE_NODEDelete the node

Never return an empty array — throws ShouldNotHappenException.

Protected Methods on AbstractRector

// Name checking
$this->isName($node, 'functionName')         // exact name match
$this->isNames($node, ['name1', 'name2'])    // match any
$this->getName($node)                         // get name string or null

// Type checking (PHPStan-powered)
$this->getType($node)                         // returns PHPStan Type
$this->isObjectType($node, new ObjectType('ClassName'))

// Traversal
$this->traverseNodesWithCallable($nodes, function (Node $node): int|Node|null {
    return null; // continue
    // or return NodeVisitor::STOP_TRAVERSAL;
    // or return NodeVisitor::DONT_TRAVERSE_CURRENT_AND_CHILDREN;
});

// Misc
$this->mirrorComments($newNode, $oldNode);    // copy comments

Creating Class Name Nodes

Always use Node\Name\FullyQualified for class references in AST nodes — never Node\Name. The string must not have a leading backslash. See references/node-types.md (Creating Class Name Nodes) for the full list of affected node properties.

Preventing Duplicate Attributes

When adding PHP attributes, use PhpAttributeAnalyzer (inject via constructor) to check if the attribute is already present. Guard non-repeatable attributes with an early return null; for repeatable attributes, only guard when the specific instance you'd add is already there. Always add a skip_attribute_already_present.php.inc fixture for non-repeatable attributes.

See references/helpers.md (PhpAttributeAnalyzer section) for injection, method signatures, and repeatability guidance.

Reducing Rule Risk

Before transforming a class or its members, consider whether the change is safe in an inheritance context. Rector rules run against arbitrary codebases, so a transformation that looks correct on a standalone class may break subclasses or consumers.

Non-final classes

If the class being transformed is not final, it may be extended. A rule that adds, removes, or changes a method/property/constant on a non-final class could silently break subclasses (e.g. method signature change, new abstract requirement, changed return type).

Ask: could subclasses be affected by this transformation?

  • If yes and the risk is real, guard with isFinal() and skip non-final classes. Add a skip_non_final_class.php.inc fixture.
  • If the rule is intentionally broad and the risk is accepted, document that reasoning in the rule's getRuleDefinition() description.
  • Some rules legitimately target non-final classes (e.g. adding a type declaration to a public method) — in those cases consider whether it's safe to apply on public/protected members (see below).
// Skip if class is not final
$classNode = $this->betterNodeFinder->findParentType($node, Class_::class);
if (! $classNode instanceof Class_) {
    return null;
}
if (! $classNode->isFinal()) {
    return null;
}

Public and protected members

Public and protected methods, properties, and constants form the class's API contract — both for external callers and for subclasses. Changing them (renaming, adding/removing parameters, changing types, adding attributes) carries more risk than changing private members.

Ask: is this member public or protected?

  • private members — safe to transform; no external or inheritance contract.
  • protected members — subclasses may override or depend on the original signature. Consider skipping, or at minimum add skip fixtures for protected cases.
  • public members — broadest risk. Weigh whether the rule should be limited to private, opt-in via configuration, or require the class to be final.
// Example: only transform private methods
if (! $node->isPrivate()) {
    return null;
}

// Example: skip public/protected properties
if ($node->isPublic() || $node->isProtected()) {
    return null;
}

Injected Services

Inject via constructor (autowired by DI container):

public function __construct(
    private readonly BetterNodeFinder $betterNodeFinder,
    // ... other services
) {}
  • $this->nodeFactory — create nodes (see references/helpers.md)
  • $this->nodeComparator — compare nodes structurally
  • $this->betterNodeFinder — search within nodes (inject via constructor)
  • PHPDoc manipulation: inject PhpDocInfoFactory + DocBlockUpdater

Configurable Rules

use Rector\Contract\Rector\ConfigurableRectorInterface;
use Symplify\RuleDocGenerator\ValueObject\CodeSample\ConfiguredCodeSample;

final class MyRector extends AbstractRector implements ConfigurableRectorInterface
{
    private string $targetClass = 'OldClass';

    public function configure(array $configuration): void
    {
        $this->targetClass = $configuration['target_class'] ?? $this->targetClass;
    }

    public function getRuleDefinition(): RuleDefinition
    {
        return new RuleDefinition('...', [
            new ConfiguredCodeSample('before', 'after', ['target_class' => 'OldClass']),
        ]);
    }
}

PHP Version Gating

use Rector\VersionBonding\Contract\MinPhpVersionInterface;
use Rector\ValueObject\PhpVersionFeature;

final class MyRector extends AbstractRector implements MinPhpVersionInterface
{
    public function provideMinPhpVersion(): int
    {
        return PhpVersionFeature::ENUM; // PHP 8.1+
    }
}

See references/php-versions.md for all PhpVersionFeature constants.

rector.php Registration

use Rector\Config\RectorConfig;

return RectorConfig::configure()
    ->withRules([MyRector::class])
    // configurable rule:
    ->withConfiguredRule(MyConfigurableRector::class, ['key' => 'value']);

Namespace Convention

Rules live at: rules/[Category]/Rector/[NodeType]/[RuleName]Rector.php Tests live at: rules-tests/[Category]/Rector/[NodeType]/[RuleName]Rector/

Categories: CodeQuality, CodingStyle, DeadCode, EarlyReturn, Naming, Php52–Php85, Privatization, Removing, Renaming, Strict, Transform, TypeDeclaration

Writing Tests

Every rule needs a test class extending AbstractRectorTestCase with fixtures in a Fixture/ directory and a config in config/configured_rule.php.

Fixture tip: Write only the input section, run the test, and FixtureFileUpdater fills the expected output automatically.

Skip fixtures: One skip_*.php.inc file per no-change scenario — single section, no ----- separator.

See references/testing.md for the full test class template, fixture format, config file formats, configurable rule variants, and special cases.

Reference Files

  • references/configurable-rules.md — All built-in configurable rules with config examples (check this before writing a custom rule)
  • references/node-types.md — PhpParser node type quick reference (FuncCall, MethodCall, Class_, etc.)
  • references/helpers.md — NodeFactory methods, BetterNodeFinder, NodeComparator, PhpDocInfo
  • references/php-versions.md — PhpVersionFeature constants by PHP version
  • references/testing.md — Full test structure, fixture format, configurable rule testing, special cases

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.