Rector Rules Laravel Package

Product Decisions This Supports

• PHPUnit Modernization Initiatives:

  • Automate migration from legacy PHPUnit annotations (e.g., @test) to modern attributes (e.g., #test) to align with PHP 8.1+ standards and reduce technical debt.
  • Enable seamless adoption of PHPUnit 9+ features by standardizing test syntax across large codebases.
  • Support trunk-based development by catching deprecated test syntax early in CI/CD pipelines.

• Code Quality & Maintainability Initiatives:

  • Extend existing Rector-based refactoring to include test suite modernization, reducing inconsistencies between legacy and modern test patterns.
  • Integrate with PHPUnit best practices (e.g., #[DataProvider], #[Before]) to improve test readability and maintainability.
  • Build vs. Buy Decision:
    • Buy: Justify adoption over custom scripts for test attribute migration, leveraging battle-tested Rector rules with minimal maintenance.
    • Build: Only if the package lacks support for custom PHPUnit extensions or niche testing frameworks.

• Use Cases:

  • Legacy Test Suite Refactoring: Modernize PHPUnit tests in large Laravel applications (e.g., >1,000 test files).
  • Pre-Merge Checks: Enforce modern PHPUnit syntax in pull requests via Git hooks or CI (e.g., GitHub Actions).
  • Post-Release Cleanup: Standardize test syntax after major framework upgrades (e.g., PHPUnit 8 → 9).

When to Consider This Package

• Adopt When:

  • Your team uses PHPUnit 8+ and wants to migrate to attributes (e.g., #test instead of @test).
  • You maintain a large test suite (>500 test files) where manual refactoring is impractical.
  • Your CI/CD pipeline already uses Rector or PHP-CS-Fixer and you want to extend it with test-specific rules.
  • Legacy PHPUnit annotations (e.g., @dataProvider) exist in your codebase and need modernization.
  • You prioritize consistent test syntax to improve readability and reduce onboarding friction.

• Look Elsewhere When:

  • Your team values flexibility over standardization (e.g., allows mixed annotations/attributes).
  • You use alternative testing frameworks (e.g., Pest, Laravel’s built-in testing) that don’t support PHPUnit attributes.
  • Your test suite is small or greenfield (manual updates may suffice).
  • You’re using custom PHPUnit extensions not covered by the package’s rules.

How to Pitch It (Stakeholders)

For Executives:

*"This new Rector rule automates the migration from legacy PHPUnit annotations (e.g., @test) to modern attributes (e.g., #test), a critical step for teams upgrading to PHP 8.1+ or PHPUnit 9+. By integrating it into our CI/CD pipeline, we can:

• Eliminate manual refactoring of 1,000+ test files, saving 50+ hours of developer time.
• Reduce bugs from inconsistent test syntax (e.g., mixed @test and #test).
• Future-proof our test suite for PHPUnit’s evolving standards. The cost is negligible (MIT-licensed, open-source), and the ROI comes from faster releases and lower maintenance costs. We’ll pilot it on [Legacy Project Y] and measure impact in 2 months."*

For Engineering Teams:

*"This adds a new Rector rule to modernize PHPUnit tests:

• PHPUnit\ReplaceTestAttributeWithTestPrefixRector: Converts legacy annotations (e.g., @test) to attributes (e.g., #test).
• Example:

  // Before
  class UserTest extends TestCase {
      public function testLogin() { ... }
  }
  
  // After
  class UserTest extends TestCase {
      #[Test]
      public function testLogin() { ... }
  }
  

How it works:

1. Install the package:

   composer require ergebnis/rector-rules --dev
   

2. Configure in rector.php:

   return static function (RectorConfig $rectorConfig): void {
       $rectorConfig->ruleWithConfiguration(
           PHPUnit\ReplaceTestAttributeWithTestPrefixRector::class,
           []
       );
   };
   

3. Run:

   rector process tests --dry-run
   

Why now?

• Aligns with PHPUnit 9+ and PHP 8.1+ standards.
• Works alongside existing Rector/PHP-CS-Fixer rules.
• Zero runtime overhead—only runs during development/deployment."*

For Developers:

*"Sick of manually updating PHPUnit tests from @test to #test? This package auto-fixes it for you. Key perks:

• One command to modernize all tests:

  rector process tests
  

• Supports bulk migrations: Handles @dataProvider, @before, etc.
• Safe to use: Dry-run mode (--dry-run) previews changes. Pro tip: Add it to your php-cs-fixer config or Git hooks to catch deprecated syntax early. Try it:

composer require ergebnis/rector-rules --dev
rector process tests --dry-run
```"