Rector Rules Laravel Package

Technical Evaluation

Architecture Fit

• Leverages Rector’s Core: The package extends rector/rector, a PHP refactoring tool, making it a natural fit for Laravel/PHP projects requiring automated code modernization. Rector is already widely adopted in Laravel ecosystems (e.g., for PHP 8.x migrations, PSR compliance, or legacy code cleanup).
• Non-Invasive: Rules operate at the AST (Abstract Syntax Tree) level, meaning they modify code without requiring runtime changes. This aligns with Laravel’s dependency injection and service container patterns, where refactoring should not disrupt existing logic.
• Opportunity for CI/CD Integration: Rules like ReplaceTestAttributeWithTestPrefixRector (PHPUnit 9+ compatibility) or Faker\GeneratorPropertyFetchToMethodCallRector (deprecation fixes) directly address maintenance debt, reducing manual effort in PR reviews.

Integration Feasibility

• Composer-Based: Installation via composer require --dev ensures zero runtime overhead (dev-only dependency), fitting Laravel’s composer.json workflows.
• Configuration-Driven: Rules like ReferenceNamespacedSymbolsRelativeToNamespacePrefixRector require explicit configuration, reducing accidental refactoring risks. This is critical for Laravel’s namespaced structure (e.g., App\Services\, App\Http\Controllers\).
• PHP Version Support: Supports PHP 8.2+ (Laravel’s LTS range), but PHP 7.4/8.0/8.1 are deprecated. A migration path must be defined for legacy Laravel apps (e.g., 7.x/8.x).

Technical Risk

• Rule Collisions: Some rules (e.g., SortAssociativeArrayByKeyRector) may conflict with existing code style tools (PHP-CS-Fixer, Laravel Pint). Validation is needed to avoid unintended side effects.
• Test Coverage Gaps: While the package has 100% code coverage, real-world Laravel use cases (e.g., custom facades, dynamic class loading) may expose edge cases. Unit/integration tests should validate edge cases (e.g., Illuminate\Support\Facades\Route usage).
• Performance Impact: Rector runs during CI/CD, so large codebases (e.g., monorepos) may slow builds. Parallelization or incremental analysis (via Rector’s --dry-run) should be tested.
• Backward Compatibility: Rules like ReplaceTestAttributeWithTestPrefixRector break existing tests. A gradual rollout (e.g., per feature branch) is recommended.

Key Questions

1. Prioritization:
   • Which rules align with current technical debt (e.g., PHPUnit 9 migration, Faker deprecations)?
   • Should this be mandatory (via CI checks) or optional (developer-driven)?
2. Configuration Management:
   • How will namespacePrefixes be defined for Laravel’s modular structure (e.g., App\, Modules\)?
   • Should discoverNamespacePrefixes be enabled by default?
3. CI/CD Strategy:
   • Where should Rector run? Pre-commit (PHPStan), PR checks, or post-merge?
   • How will false positives (e.g., SortMatchArmsByConditionalRector misordering) be handled?
4. Team Adoption:
   • Will developers need training on Rector’s output (e.g., diff previews)?
   • How will conflicts (e.g., manual vs. automated refactoring) be resolved?
5. Long-Term Maintenance:
   • Who will update rules as Laravel evolves (e.g., new facades, PHP 9.0 features)?
   • Should this be vendor-maintained or in-house customized?

Integration Approach

Stack Fit

• Laravel Ecosystem:
  • PHPUnit: Rules like ReplaceTestAttributeWithTestPrefixRector directly support Laravel’s testing stack (PHPUnit 9+).
  • Faker: Used in Laravel’s factories/seeding, so GeneratorPropertyFetchToMethodCallRector is highly relevant.
  • Namespacing: Laravel’s PSR-4 autoloading makes ReferenceNamespacedSymbolsRelativeToNamespacePrefixRector valuable for consolidating use statements (e.g., use Illuminate\Support\Facades\).
  • Legacy Code: Laravel apps often mix old PHP (7.4/8.0) with modern features; Rector can gradually modernize them.
• Tooling Synergy:
  • PHPStan: Can run alongside Rector for static analysis.
  • Pint/PHP-CS-Fixer: Rules like SortAssociativeArrayByKeyRector may overlap; order of execution must be defined.
  • GitHub Actions: Easy to integrate into CI pipelines for automated refactoring.

Migration Path

1. Pilot Phase:
   • Start with non-breaking rules (e.g., RemoveNamedArgumentForSingleParameterRector, Faker updates).
   • Test on a single module (e.g., App\Services\) before full adoption.
2. Configuration Setup:
   • Define rector.php with Laravel-specific prefixes:

     return [
         'rules' => [
             new \Ergebnis\Rector\Rules\Files\ReferenceNamespacedSymbolsRelativeToNamespacePrefixRector(
                 namespacePrefixes: ['App\\', 'Illuminate\\Support\\Facades\\']
             ),
             new \Ergebnis\Rector\Rules\PHPUnit\ReplaceTestAttributeWithTestPrefixRector(),
         ],
     ];
     

3. Incremental Rollout:
   • Phase 1: Run in CI (dry-run) to validate changes.
   • Phase 2: Apply to feature branches first.
   • Phase 3: Enforce in main branch via CI checks.
4. Legacy Support:
   • For Laravel <8.0, use Rector’s --php-version flag or custom rules to avoid PHP 8.x-only features.

Compatibility

• Laravel-Specific Considerations:
  • Facades: ReferenceNamespacedSymbolsRelativeToNamespacePrefixRector may need exclusions for Facade::class usages.
  • Dynamic Classes: Laravel’s service container may generate classes at runtime; Rector’s static analysis might miss these.
  • Blade Templates: Rector does not process Blade files by default; exclude resources/views/ from analysis.
• Dependency Conflicts:
  • Ensure no version conflicts with rector/rector (e.g., Laravel’s phpunit/phpunit vs. Rector’s PHPUnit rules).
  • Test with Laravel’s default packages (e.g., laravel/framework) to avoid rule misfires.

Sequencing

1. Pre-Refactor:
   • Run composer require --dev ergebnis/rector-rules.
   • Configure rector.php with safe rules first.
2. Validation:
   • Use --dry-run to preview changes:

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

3. Execution:
   • Apply to specific paths (e.g., src/, tests/) to avoid vendor/ or node_modules/.
   • Example command:

     vendor/bin/rector process src tests --config rector.php
     

4. Post-Refactor:
   • Commit changes and verify tests pass.
   • Update CI to run Rector on PRs.

Operational Impact

Maintenance

• Rule Updates:
  • Subscribe to ergebnis/rector-rules for new rules (e.g., Laravel 11 compatibility).
  • Customize rules if Laravel introduces new patterns (e.g., #[Test] alternatives).
• Configuration Drift:
  • Document rector.php in the team’s style guide.
  • Use GitHub Actions to auto-update configurations (e.g., new namespace prefixes).
• Deprecation Handling:
  • Rules like Faker\GeneratorPropertyFetchToMethodCallRector may need retirement as Faker stabilizes.

Support

• Developer Onboarding:
  • Add a README section explaining Rector’s role in the project.
  • Provide templates for rector.php configurations.
• Troubleshooting:
  • Log rule failures to a Slack channel or Jira ticket for review.
  • Maintain a list of excluded files/directories (e.g., node_modules/, storage/).
• Escalation Path:
  • For false positives, allow developers to