Rector Php Rules Laravel Package

Product Decisions This Supports

• Enforcing a strict, opinionated code quality standard across the codebase to reduce technical debt and improve maintainability. This aligns with initiatives to standardize development practices and reduce inconsistencies.
• Accelerating onboarding by eliminating subjective code review friction (e.g., "why is this assert() here?" or "why are there comments everywhere?"). Rules like NoCommentsOutsideInterfaceMethodDocBlockRector and NoPhpstanIgnoreRector automate enforcement of best practices.
• Improving test reliability by enforcing deterministic assertions in functional tests (e.g., NoAssertInsideIfInFunctionalTestsRector and NoArrayAssertContainsInTestsRector). This supports a shift-left testing strategy where tests are more predictable and easier to debug.
• Architectural consistency by mandating PSR Clock (RequirePsrClockInterfaceRector) and banning superglobals (NoSuperglobalAccessRector), reducing coupling and making the codebase more testable and maintainable.
• CI/CD integration as a gatekeeper for code quality. Rules like NoTodoCommentRector and NoSilentFallbackRector prevent technical debt from accumulating, while dry-run markers (// RECTOR-BAN) make violations visible without auto-rewriting code.
• Roadmap for PHP 8.3+ modernization: This package aligns with efforts to adopt modern PHP features (e.g., strict typing, PSR standards) and deprecate legacy patterns (e.g., assert(), superglobals).
• Build vs. buy: Justify investing in tooling to enforce standards rather than relying on manual reviews or ad-hoc scripts. Reduces the need for custom linting tools or manual audits.

When to Consider This Package

• Adopt if:

  • Your team struggles with inconsistent code quality (e.g., mixed assertions, superglobals, or @phpstan-ignore annotations).
  • You’re migrating to PHP 8.3+ and want to enforce modern best practices (e.g., PSR Clock, strict assertions).
  • Functional tests are flaky due to non-deterministic assertions or direct DB/event dispatch.
  • You’re investing in CI/CD and want to gate code quality automatically (e.g., block merges with violations).
  • Your codebase has legacy technical debt (e.g., assert(), constructor fallbacks, or narrative comments) that slows down development.
  • You prioritize test reliability and want to eliminate conditional assertions or array-based checks.

• Look elsewhere if:

  • Your team resists strict rules or lacks buy-in for opinionated tooling. This package enforces a rigid standard; cultural alignment is critical.
  • You’re not using PHP 8.3+ (the package targets modern PHP features).
  • Your project is small or experimental and doesn’t need enforced standards.
  • You prefer manual reviews over automated enforcement (e.g., for nuanced architectural decisions).
  • Your codebase already adheres to these standards and doesn’t need additional gates.
  • You’re heavily invested in legacy patterns (e.g., superglobals, assert()) that would require significant refactoring to comply.

How to Pitch It (Stakeholders)

For Executives:

"This package automates the enforcement of our highest-quality coding standards—eliminating technical debt, reducing bugs, and speeding up development. By integrating it into our CI pipeline, we’ll catch issues early (e.g., flaky tests, superglobals, or ignored type errors) before they reach production. It’s like having a senior developer review every line of code, but at scale. The upfront cost is minimal (a Composer install and CI tweak), and the long-term payoff is fewer fires, faster onboarding, and more reliable software. Think of it as ‘code quality on autopilot.’"

Key Outcomes:

• Fewer production bugs from silent failures (e.g., assert() under zend.assertions=-1).
• Faster onboarding (no more debates over // TODO or @phpstan-ignore).
• More maintainable codebase (no narrative comments, no superglobals).
• CI that blocks bad code, not just runs tests.

For Engineering Teams:

*"This is a Rector rule set that turns our team’s best practices into automated, enforceable standards. No more arguing about whether assert() is okay or why someone used $_ENV in production code—the tool will reject it. Here’s what it does:

• Bans assert() in production code (replaces it with explicit throw for visible failures).
• Forces PSR Clock (no more new DateTime or time() calls).
• Cleans up tests (no conditional assertions, no direct DB/event dispatch).
• Strips comments (except PHPStan tags) to keep code clean and self-documenting.
• Blocks @phpstan-ignore (forces fixes instead of suppressions).

How it works:

1. Add it to composer.json (amashukov/rector-php-rules).
2. Configure it in rector.php (takes 10 minutes).
3. Run rector process --dry-run in CI—it’ll flag violations without rewriting code (you decide how to fix).
4. Merge only when it passes.

Why now?

• We’re migrating to PHP 8.3+, and this enforces modern patterns.
• Flaky tests are a pain point—this makes them deterministic.
• Onboarding is slow because of inconsistent code; this standardizes it.

Trade-offs:

• Strict by design: If you disagree with a rule (e.g., you need assert()), you’ll have to opt out or refactor.
• Upfront effort: Requires a one-time setup and some code changes, but pays off long-term.

Next steps:

• Let’s try it on a non-critical branch (e.g., a feature flag) to see how it feels.
• We’ll need to update CI to fail builds on violations.
• I’ll provide a rector.php template to get started."*

For Developers: *"This is your new code quality cop. It’ll:

• Catch your mistakes before CI (e.g., assert() in production, superglobals, or @phpstan-ignore).
• Make tests more reliable (no more ‘assertContains’ hacks or conditional checks).
• Keep the codebase clean (no comments cluttering up the code).
• Enforce modern PHP (PSR Clock, strict assertions).

How to use it:

1. Install it: composer require --dev amashukov/rector-php-rules.
2. Add the rules to your rector.php (I’ll share a template).
3. Run rector process --dry-run locally before pushing.
4. Fix the violations it flags (they’ll show up as // RECTOR-BAN comments).

Pro tip: Start with a few rules (e.g., NoSuperglobalAccessRector or NoAssertCallInSrcRector) and gradually add more as you get comfortable. It’s easier to opt in than to undo later!"*