Rector Php Rules Laravel Package

Technical Evaluation

Architecture Fit

• Strong alignment with Laravel’s dependency injection (DI) and testing paradigms: The package enforces PSR Clock, bans superglobals, and mandates DI-friendly patterns (e.g., no getenv() in src/). This aligns with Laravel’s evolving best practices (e.g., Symfony’s DI container, Illuminate\Contracts\Container\BindingResolutionException).
• Complementary to Laravel’s testing stack: Rules like NoDirectDbMutationInFunctionalTestsRector and NoDirectDispatchInFunctionalTestsRector enforce Laravel’s recommended testing practices (e.g., using HttpTestCase, DatabaseTransactions, or RefreshDatabase traits).
• Opinionated but configurable: The rules are designed for strict enforcement but can be selectively applied (e.g., skipping migrations or legacy code via RectorConfig::skip()).
• PHP 8.3+ requirement: Laravel 10+ (PHP 8.2+) and Laravel 11 (PHP 8.3+) are compatible, but some features (e.g., match expressions) may require Laravel 11+ for full integration.

Integration Feasibility

• Low friction for Laravel projects: The package integrates seamlessly with Laravel’s existing tooling (e.g., rector.php can coexist with Laravel’s phpunit.xml and composer.json scripts).
• CI/CD compatibility: Rules are detection-first (add // RECTOR-BAN markers), making them ideal for CI gates (e.g., GitHub Actions, GitLab CI) without breaking builds during initial adoption.
• No Laravel-specific dependencies: The package is framework-agnostic, reducing risk of conflicts with Laravel’s core or third-party packages.
• YAML support: Useful for Laravel’s config files (e.g., config/*.php or config/*.yaml), though Laravel primarily uses PHP arrays for configs.

Technical Risk

• False positives in legacy code: Laravel projects with older patterns (e.g., assert(), superglobals, or getenv()) may require significant refactoring. Mitigate by:
  • Running in dry-run mode (rector process --dry-run) first.
  • Using RectorConfig::skip() to exclude problematic directories (e.g., migrations/, vendor/).
• Overly strict for some use cases: Rules like NoTodoCommentRector or NoCommentsOutsideInterfaceMethodDocBlockRector may clash with Laravel’s convention of using PHPDoc in controllers or service providers. Solution: Disable specific rules or adjust paths.
• Performance overhead: Rector runs add build time. For large codebases, consider:
  • Running in CI only (not locally).
  • Parallelizing Rector with other static analyzers (e.g., PHPStan).
• Limited adoption: The package has 0 stars/dependents, indicating unproven stability. Mitigation:
  • Test on a feature branch first.
  • Monitor for updates or forks (e.g., Laravel-specific forks).

Key Questions for the TPM

1. Adoption scope:
   • Should this be enforced across all teams or piloted in a single service first?
   • How will legacy code (e.g., pre-Laravel 10) be handled? (e.g., gradual migration vs. blanket exclusion)
2. CI integration:
   • Should Rector run on every commit or nightly to avoid CI slowdowns?
   • How will false positives be triaged? (e.g., allowlist exceptions in rector.php)
3. Developer experience:
   • Will teams need training on the new rules (e.g., PSR Clock usage, DI patterns)?
   • How will comment hygiene (e.g., stripped docblocks) be communicated to designers/architects?
4. Tooling compatibility:
   • Does Laravel’s IDE (PHPStorm/VSCode) need configuration to handle // RECTOR-BAN markers?
   • Will this conflict with Laravel Forge/Envoyer or other deployment tools?
5. Long-term maintenance:
   • Who will update the Rector rules if the package evolves?
   • Should this be vendor-locked or version-pinned in composer.json?

Integration Approach

Stack Fit

• Laravel 10+ (PHP 8.2+) / Laravel 11 (PHP 8.3+):
  • Fully compatible with PHP 8.3+ features (e.g., match expressions, typed properties).
  • Partial compatibility with Laravel 10 (PHP 8.2): Some rules (e.g., NoAssertInsideIfInFunctionalTestsRector) may need adjustments for match expressions.
• Tooling stack:
  • Rector: Already used in Laravel for upgrades (e.g., rector/rector for PHP 8.0+ migrations).
  • PHPStan: Works alongside Rector (e.g., phpstan-baseline can be phased out via NoPhpstanIgnoreRector).
  • PestPHP/Laravel TestCase: Rules like NoDirectDbMutationInFunctionalTestsRector align with Pest’s refreshDatabase() or Laravel’s DatabaseMigrations.
• CI/CD:
  • GitHub Actions/GitLab CI: Add a step to run Rector in CI (e.g., rector process --dry-run).
  • Parallelization: Run Rector alongside PHPStan/Pint for faster feedback.

Migration Path

1. Phase 1: Assessment (1–2 weeks)
   • Run rector process --dry-run on main branch to identify violations.
   • Document high-impact changes (e.g., PSR Clock adoption, DI refactoring).
   • Decide on exclusions (e.g., migrations/, legacy controllers).
2. Phase 2: Pilot (2–4 weeks)
   • Apply to one service/module (e.g., a new feature or micro-service).
   • Train developers on new patterns (e.g., PSR Clock, DI, test purity).
   • Gather feedback on false positives and adjust rules.
3. Phase 3: Full Rollout (4–8 weeks)
   • Gradually enable rules across the codebase.
   • Use feature flags or branch protection to enforce Rector in CI.
   • Deprecate legacy patterns (e.g., assert(), getenv()) via deprecation warnings.
4. Phase 4: Enforcement (ongoing)
   • Block merges to main if Rector fails.
   • Archive allowed exceptions in rector.php with comments.

Compatibility

• Laravel-specific adjustments:
  • Exclude app/Providers/: Some providers use getenv() or superglobals for legacy config.
  • Adjust test paths: Laravel’s tests/Feature/ and tests/Unit/ may need custom skips.
  • PSR Clock: Replace now()/Carbon with Psr\Clock\ClockInterface (use symfony/clock or spatie/laravel-psr-clock).
• Third-party packages:
  • Vendor code: Skip vendor/ directory in rector.php.
  • Legacy packages: Use RectorConfig::skip() for known problematic packages (e.g., old Laravel addons).
• Database migrations: Exclude database/migrations/ to avoid breaking existing logic.

Sequencing

Operational Impact

Maintenance

• Pros:
  • Reduces technical debt: Rules like NoPhpstanIgnoreRector