Rector Laravel Package

Getting Started

Minimal Setup for First Use

1. Install the Package Add to your composer.json under require-dev:

   composer require --dev ibexa/rector:^5.0
   

2. Create Rector Config Generate a minimal rector.php in your project root:

   declare(strict_types=1);
   
   use Ibexa\Contracts\Rector\Sets\IbexaSetList;
   use Rector\Config\RectorConfig;
   
   return RectorConfig::configure()
       ->withPaths([__DIR__ . '/src', __DIR__ . '/tests'])
       ->withSets([IbexaSetList::IBEXA_50]);
   

3. Run a Dry Test Validate changes before applying:

   php vendor/bin/rector process src --dry-run
   

4. Apply Changes Once confirmed, run:

   php vendor/bin/rector process src
   

First Use Case: Ibexa 4.x → 5.0 Migration

• Target: Automate deprecated API removals (e.g., ezpublish namespace → ibexa).
• Workflow:
  1. Configure IBEXA_50 set in rector.php.
  2. Run against src/ and tests/ directories.
  3. Commit changes incrementally (e.g., per feature module).

Implementation Patterns

Core Workflows

1. Version-Specific Upgrades

• Pattern: Use IbexaSetList::IBEXA_XY constants to target specific Ibexa versions.

  // For Ibexa 4.6 → 5.0
  ->withSets([IbexaSetList::IBEXA_50])
  

• Tip: Chain multiple sets for staged migrations:

  ->withSets([
      IbexaSetList::IBEXA_46_TO_50, // Custom intermediate set
      IbexaSetList::IBEXA_50
  ])
  

2. Directory-Specific Refactoring

• Pattern: Scope rules to subdirectories (e.g., src/Controller/):

  ->withPaths([__DIR__ . '/src/Controller'])
  

• Use Case: Isolate risky refactors (e.g., legacy ezplatform bundles).

3. CI/CD Integration

• Pattern: Add to phpunit.xml or Git hooks:

  <!-- phpunit.xml -->
  <php>
      <env name="RECTOR_PROCESS" value="1"/>
  </php>
  

• Script: Run in CI pre-commit:

  if [ "$RECTOR_PROCESS" = "1" ]; then
      php vendor/bin/rector process src --dry-run
  fi
  

4. Custom Rule Extension

• Pattern: Extend existing rules via Rector’s plugin system:

  use Ibexa\Rector\Set\IbexaSetList;
  use Rector\Config\RectorConfig;
  
  return RectorConfig::configure()
      ->withSets([IbexaSetList::IBEXA_50])
      ->withCustomRuleSets([new CustomIbexaRuleSet()]);
  

• Example: Add a rule to rename ezplatform services:

  class RenameEzplatformServices extends AbstractRector {
      public function refactor(PhpNode $node): ?PhpNode {
          // Logic to rename services
      }
  }
  

Integration Tips

• Laravel Compatibility:
  • Use rector/rector’s Laravel rules alongside Ibexa sets:

    ->withSets([
        IbexaSetList::IBEXA_50,
        Rector\Set\LaravelSetList::LARAVEL_90
    ])
    

• Database Migrations:
  • Pair with ibexa/migrations for schema updates:

    php vendor/bin/rector process src
    php vendor/bin/ibexa migrations:migrate
    

• Testing:
  • Run tests post-refactor to catch edge cases:

    php vendor/bin/rector process src --parallel
    php artisan test
    

Gotchas and Tips

Pitfalls

1. False Positives in Dry Runs

   • Issue: Rector may flag safe changes (e.g., unused imports) as critical.
   • Fix: Use --skip-errors-on-warnings or manually review diffs:

     php vendor/bin/rector process src --dry-run --skip-errors-on-warnings
     

2. Namespace Collisions

   • Issue: Ibexa’s ezpublish → ibexa rename may conflict with custom namespaces.
   • Fix: Exclude problematic directories:

     ->withExcludedPaths([__DIR__ . '/vendor', __DIR__ . '/custom-ez'])
     

3. PHP Version Mismatches

   • Issue: Ibexa 5.0+ requires PHP 8.1+; older PHP may fail.
   • Fix: Use Docker or a VM for testing:

     FROM php:8.1-cli
     RUN composer require ibexa/rector:^5.0
     

4. Stateful Refactors

   • Issue: Some rules (e.g., RemoveLegacyClassAliasRector) may break builds if not applied fully.
   • Fix: Commit changes incrementally or use --parallel for large codebases.

Debugging

• Verbose Output: Enable debug mode to trace rule execution:

  php vendor/bin/rector process src --verbose
  

• Rule-Specific Logging: Add Rector\Logging\LoggerInterface to custom rules for debugging:

  public function __construct(private LoggerInterface $logger) {}
  $this->logger->info('Processing node: ' . $node->getType());
  

Configuration Quirks

1. Caching
   • Tip: Disable caching for first runs to avoid stale rule sets:

     ->withCache(false)
     

2. Parallel Processing
   • Tip: Use --parallel for multi-core speedups (but test thoroughly):

     php vendor/bin/rector process src --parallel
     

3. Symfony Dependency Injection
   • Issue: Ibexa’s DI container may need manual updates post-refactor.
   • Fix: Run php bin/console debug:container to validate services.

Extension Points

1. Custom Rule Sets

   • How: Create a CustomIbexaRuleSet class extending AbstractRuleSet:

     class CustomIbexaRuleSet extends AbstractRuleSet {
         public function getRules(): array {
             return [
                 new RenameEzplatformServices(),
             ];
         }
     }
     

   • Register:

     ->withCustomRuleSets([new CustomIbexaRuleSet()])
     

2. Pre/Post-Refactor Hooks

   • How: Use Rector’s Rector\Contract\Rector\RectorInterface to add logic:

     class PreRefactorValidator extends AbstractRector {
         public function refactor(PhpNode $node): ?PhpNode {
             if ($node instanceof ClassMethod && $node->name->toString() === 'legacyMethod') {
                 throw new \RuntimeException('Skip refactor: method is legacy.');
             }
             return null;
         }
     }
     

3. Integration with Ibexa CLI

   • Tip: Alias Rector commands in composer.json:

     "scripts": {
         "rector": "vendor/bin/rector process src",
         "rector:dry": "vendor/bin/rector process src --dry-run"
     }
     

   • Usage:

     composer rector