Rector Rules Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require --dev ergebnis/rector-rules
   

2. Configure Rector in rector.php:

   use Ergebnis\Rector\Rules\Sets\ErgebnisRules;
   
   return [
       ErgebnisRules::set(),
       // Other Rector rules...
   ];
   

3. Run Rector:

   vendor/bin/rector process src
   

First Use Case: PHPUnit Attribute Migration

Apply the new ReplaceTestAttributeWithTestPrefixRector to migrate legacy PHPUnit test classes from annotations to attributes:

vendor/bin/rector process tests --rule "Ergebnis\Rector\Rules\PHPUnit\ReplaceTestAttributeWithTestPrefixRector"

Implementation Patterns

Workflow Integration

1. CI/CD Pipeline (updated for new rule):

   # .github/workflows/rector.yml
   jobs:
     rector:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
         - run: composer require --dev ergebnis/rector-rules
         - run: vendor/bin/rector process tests --dry-run --parallel --rule "Ergebnis\Rector\Rules\PHPUnit\ReplaceTestAttributeWithTestPrefixRector"
   

2. Pre-commit Hook (with PHPUnit focus):

   return [
       ErgebnisRules::set(),
       'autoload_paths' => [__DIR__ . '/tests'],
       'parallel' => true,
       'cache_directories' => [__DIR__ . '/var/rector'],
       'exclude_paths' => ['src/'], // Focus on tests
   ];
   

Rule-Specific Patterns

1. PHPUnit Attribute Migration:

   // rector.php
   return [
       ErgebnisRules::set(),
       'rules' => [
           PHPUnit\ReplaceTestAttributeWithTestPrefixRector::class => [
               'prefix' => 'test_', // Default prefix for test methods
               'skip' => [
                   'Feature\\LegacyAnnotationsTest', // Exclude specific classes
               ],
           ],
       ],
   ];
   

2. Combined Test Modernization:

   vendor/bin/rector process tests --rule "Ergebnis\Rector\Rules\PHPUnit\ReplaceTestAttributeWithTestPrefixRector" --rule "Ergebnis\Rector\Rules\Faker\GeneratorPropertyFetchToMethodCallRector"
   

3. Selective Test Migration:

   vendor/bin/rector process tests/Unit --rule "Ergebnis\Rector\Rules\PHPUnit\ReplaceTestAttributeWithTestPrefixRector" --dry-run
   

Gotchas and Tips

Common Pitfalls

1. PHPUnit Attribute Rule Limitations:

   • Issue: ReplaceTestAttributeWithTestPrefixRector only handles method names prefixed with @test (e.g., @testLogin). Explicit annotations like @test("login") are ignored.
   • Fix: Use --dry-run first to identify unsupported cases, then manually refactor or extend the rule.

2. Namespace Collisions in Tests:

   • Issue: Combining ReferenceNamespacedSymbolsRelativeToNamespacePrefixRector with PHPUnit rules may cause conflicts in test namespaces.
   • Fix: Exclude test directories from namespace refactoring:

     'exclude_paths' => ['tests/'],
     

3. Test Prefix Conflicts:

   • Issue: Default test_ prefix may conflict with existing method names (e.g., testLogin vs testLoginUser).
   • Fix: Customize the prefix or use a more specific pattern:

     'rules' => [
         ReplaceTestAttributeWithTestPrefixRector::class => [
             'prefix' => 'should_', // Alternative prefix
         ],
     ],
     

4. Legacy Test Structure:

   • Issue: Tests using setUpBeforeClass or tearDownAfterClass may break if method names are modified.
   • Fix: Run the rule in stages or exclude problematic classes.

Debugging Tips

1. Dry Run with PHPUnit Focus:

   vendor/bin/rector process tests --dry-run --rule "Ergebnis\Rector\Rules\PHPUnit\ReplaceTestAttributeWithTestPrefixRector" -vv
   

   • Identifies unsupported test cases and skipped files.

2. Rule-Specific Logging:

   // rector.php
   return [
       'logging' => true,
       'rules' => [
           PHPUnit\ReplaceTestAttributeWithTestPrefixRector::class => [
               'logging' => true,
               'prefix' => 'test_',
           ],
       ],
   ];
   

3. Partial Test Suite Migration:

   • Apply the rule to specific test groups first:

     vendor/bin/rector process tests/Unit/ --rule "Ergebnis\Rector\Rules\PHPUnit\ReplaceTestAttributeWithTestPrefixRector"
     

Extension Points

1. Custom Test Prefix Logic:

   • Extend the rector to support custom prefix patterns (e.g., regex-based):

     use Ergebnis\Rector\Rules\PHPUnit\ReplaceTestAttributeWithTestPrefixRector;
     
     class CustomTestPrefixRector extends ReplaceTestAttributeWithTestPrefixRector {
         public function getPrefix(): string {
             return 'should_' . $this->getMethodName(); // Dynamic prefix
         }
     }
     

2. Attribute-to-Annotation Hybrid:

   • Combine with other rules to migrate annotations incrementally:

     'rules' => [
         PHPUnit\ReplaceTestAttributeWithTestPrefixRector::class => [
             'prefix' => 'test_',
         ],
         PHPUnit\ReplaceAnnotationWithAttributeRector::class => [
             'skip' => ['@test'], // Skip already migrated methods
         ],
     ],
     

3. Integration with Pest:

   • Use the rule to standardize test method names in Pest test suites:

     vendor/bin/rector process tests/Pest --rule "Ergebnis\Rector\Rules\PHPUnit\ReplaceTestAttributeWithTestPrefixRector"
     

Configuration Quirks

1. Default Prefix Behavior:

   • The rule defaults to test_ prefix. Omit the configuration to use the default.

2. Case Sensitivity:

   • Prefix matching is case-sensitive. Use strtolower in custom extensions for case-insensitive logic.

3. Method Name Validation:

   • The rule skips methods that don’t start with @test. Use --dry-run to audit unsupported cases.

Performance Optimization

1. Targeted Test Processing:

   vendor/bin/rector process tests/Unit --parallel --workers 2 --rule "Ergebnis\Rector\Rules\PHPUnit\ReplaceTestAttributeWithTestPrefixRector"
   

   • Focus processing on smaller test subsets.

2. Cache Optimization:

   return [
       'cache_directories' => [__DIR__ . '/var/rector'],
       'autoload_paths' => [__DIR__ . '/tests'],
   ];
   

   • Reduces redundant parsing of test files.

3. Exclude Non-Relevant Tests:

   return [
       'exclude_paths' => [
           'tests/Integration/', // Exclude slower tests
       ],
   ];