Coding Standard Laravel Package

Technical Evaluation

Architecture Fit

• Unchanged: Remains a static analysis tool with no runtime impact, aligning with developer tooling in Laravel ecosystems.
• PHP 8.4 Compatibility: Explicitly addresses PHP 8.4 rector fixes, ensuring compatibility with newer Laravel versions (e.g., Laravel 11+).
• Rector Integration: Inlines Rector proposals for public repo compatibility, suggesting improved automated refactoring support (e.g., for Laravel-specific patterns).

Integration Feasibility

• Minimal Changes: No breaking architectural shifts; updates focus on PHP 8.4/Rector compatibility.
• Laravel-Specific Adjustments:
  • Potential for Rector rules to handle Laravel 11+ features (e.g., new Blade syntax, enums, or attributes).
  • May require testing with Laravel’s latest to avoid false positives (e.g., in app/Providers or routes/).
• Toolchain Synergy:
  • Rector integration could streamline automated upgrades (e.g., migrating from str_* to Stringable).
  • Public repo workflows imply better GitHub/GitLab CI compatibility (e.g., for open-source Laravel packages).

Technical Risk

Key Questions

1. Rector Scope:

   • Are the Rector proposals Laravel-specific, or are they generic PHP 8.4 fixes?
   • Can Rector be disabled selectively (e.g., for legacy Laravel projects)?

2. PHP 8.4 Mandate:

   • Does this block teams still on PHP 8.1/8.2? If so, what’s the deprecation path?
   • How does it interact with Laravel’s PHP version policy (e.g., Laravel 10 vs. 11)?

3. Automated Refactoring:

   • Can this replace manual upgrades (e.g., for Carbon → CarbonInterface)?
   • What’s the failure mode if Rector overwrites critical logic?

4. Long-Term Viability:

   • Is Rector integration a temporary fix or a strategic direction for the package?
   • How will it handle future PHP/Laravel features (e.g., PHP 9.0, Laravel 12)?

Integration Approach

Stack Fit

• PHP 8.4+ Core: Required for Rector fixes; aligns with Laravel 11’s PHP 8.2+ minimum (but enforces stricter).
• Tooling Layer:
  • Rector: Adds automated refactoring to the static analysis pipeline.
  • CI/CD: May increase build time due to Rector’s complexity; optimize with caching.
  • Local Dev: Rector can run via robo tasks or pre-commit hooks (but riskier for non-trivial refactors).
• Laravel-Specific:
  • Blade/Enum/Attribute Rules: If Rector includes Laravel-specific fixes, test with:
    • resources/views/ (Blade templates).
    • app/Models/ (Eloquent enums/attributes).

Migration Path

1. Assessment Phase:

   • PHP 8.4 Audit: Verify all Laravel services support PHP 8.4 (e.g., php -v, composer validate).
   • Rector Dry Run: Test Rector proposals on a sample PR to identify false positives.

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

2. Pilot Integration:

   • Phase 1: Enable only Rector fixes (no new rules) in CI for a non-production branch.
   • Phase 2: Gradually add static analysis rules, starting with low-risk files (e.g., app/Console/).

3. Full Rollout:

   • Local Dev: Add Rector to robo.phar with a --no-exec flag for safety.
   • CI Enforcement: Fail builds on Rector errors (but allow --allow-no-changes for stability).
   • Documentation: Update UPGRADE.md with PHP 8.4 migration steps.

Compatibility

Sequencing

1. Phase 1 (Week 1):

   • Upgrade PHP: Migrate CI/CD and local dev to PHP 8.4.
   • Test Rector: Run on a clone of laravel/laravel to validate fixes.

2. Phase 2 (Week 2-3):

   • CI-Only Rector: Add to GitHub Actions with --allow-no-changes.
   • Static Rules: Enable non-Rector coding standards in parallel.

3. Phase 3 (Week 4+):

   • Local Rector: Roll out to developers with opt-in pre-commit hooks.
   • Enforce: Fail builds on Rector errors (after 2 weeks of warnings).

Operational Impact

Maintenance

• Pros:
  • Rector automates upgrades, reducing manual effort for Laravel migrations.
  • PHP 8.4 alignment future-proofs the stack for Laravel 11+.
• Cons:
  • Higher maintenance cost if Rector rules break legacy code.
  • Toolchain complexity increases with Rector + static analysis + formatter.

Support

• Developer Onboarding:
  • Rector’s refactoring may surprise developers if not communicated clearly.
  • PHP 8.4 requirement could block older environments (e.g., shared hosting).
• Troubleshooting:
  • Rector errors may require manual review for false positives (e.g., in config/).
  • Documentation gap: Need runbooks for common Rector failures (e.g., "How to exclude a file").

Scaling

• Performance:
  • Rector adds ~1-2 minutes to CI (depends on repo size; cache results with --cache).
  • Local dev: Rector can be resource-intensive for large apps (use --parallel).
• Team Growth:
  • Scalable for teams adopting PHP 8.4/Laravel 11.
  • Risk: Legacy teams may resist due to PHP upgrade burden.

Failure Modes

Ramp-Up

• Training:
  • Workshop: "Rector for Laravel Up