Coding Standard Laravel Package

Technical Evaluation

Architecture Fit

• Purpose Alignment: This package is a PHP coding standard (likely a PSR-12/PSR-2 enforcer) tailored for the Broadway project (an event-sourcing library). While not a core Laravel dependency, it could enforce consistent code quality in a Laravel project using Broadway or similar event-driven architectures.
• Leverage Points:
  • Enforce Broadway-specific naming conventions (e.g., event/message naming, domain language consistency).
  • Integrate with Laravel’s existing tooling (PHPStan, Psalm, Pest) to standardize contributions.
  • Useful if the team adopts Broadway for event sourcing and wants to align coding standards.

Integration Feasibility

• Low Effort: Can be adopted via Composer (composer require --dev broadway/coding-standard).
• Tooling Compatibility:
  • Works with PHP-CS-Fixer (if the standard is PSR-compliant).
  • Can be integrated into Git hooks (e.g., pre-commit) or CI pipelines (GitHub Actions, GitLab CI).
• Customization Risk: If the standard is Broadway-specific, it may conflict with Laravel’s default PSR-12 rules (e.g., namespace prefixes, method naming).

Technical Risk

• Minimal Risk: Purely a linting/validation tool with no runtime dependencies.
• Potential Conflicts:
  • If the standard enforces Broadway-specific rules (e.g., Event suffixes), it may clash with Laravel’s conventions.
  • False positives if the team uses different naming conventions (e.g., DomainEvent vs. Event).
• Dependency Risk: No transitive dependencies (MIT-licensed, no security concerns).

Key Questions

1. Why adopt this over PSR-12/PSR-2?
   • Does the team use Broadway, or is this for consistency with an open-source project?
   • Are there Broadway-specific rules that justify deviation from Laravel’s defaults?
2. Tooling Integration
   • How will this be enforced? (PHP-CS-Fixer, Git hooks, CI?)
   • Will it block PRs or just warn?
3. Customization Needs
   • Can the standard be extended/modified to fit Laravel’s needs?
   • Are there conflicts with existing Laravel packages (e.g., spatie/laravel-activitylog)?
4. Maintenance Overhead
   • Will this require ongoing updates if Broadway evolves?
   • Is the last release (2022) a concern for long-term support?

Integration Approach

Stack Fit

• Best Fit: Projects using Broadway or needing event-sourcing consistency.
• Laravel-Specific Considerations:
  • If not using Broadway, the value is limited (PSR-12 is already standard).
  • Useful for domain-driven design (DDD) teams aligning with Broadway’s patterns.
• Alternatives:
  • php-cs-fixer (PSR-12/PSR-2) for generic Laravel projects.
  • broadway/broadway itself if event sourcing is a core requirement.

Migration Path

1. Assessment Phase:
   • Audit existing codebase for conflicts with Broadway’s standards.
   • Decide if custom rules are needed (e.g., via PHP-CS-Fixer config).
2. Tooling Setup:
   • Install via Composer:

     composer require --dev broadway/coding-standard
     

   • Configure in php-cs-fixer.dist.php (if applicable):

     return (new PhpCsFixer\Config())
         ->setRules([
             '@Broadway' => true, // Hypothetical rule set
         ]);
     

3. CI/CD Integration:
   • Add to GitHub Actions (example):

     - name: Run Coding Standard
       run: vendor/bin/php-cs-fixer fix --rules=@Broadway --dry-run
     

   • Fail builds on violations (or warn first).

Compatibility

• PHP Version: Likely compatible with Laravel’s PHP 8.0+ support.
• Laravel Version: No direct dependency, but Broadway’s compatibility with Laravel (e.g., v1.x for Laravel 8/9) should be checked.
• Conflict Risk:
  • Low if used as a supplemental standard (not replacing PSR-12).
  • High if enforcing Broadway-specific rules that conflict with Laravel’s ecosystem.

Sequencing

1. Phase 1: Adopt as a linter-only tool (no blocking).
2. Phase 2: Enforce in CI (fail builds on violations).
3. Phase 3: Extend to pre-commit hooks (if team agrees).
4. Phase 4: Customize rules (if needed) via PHP-CS-Fixer.

Operational Impact

Maintenance

• Low Effort:
  • No runtime impact; purely a development-time tool.
  • Updates can be delayed if Broadway’s standard is stable.
• Dependency Management:
  • Monitor Broadway’s releases for standard updates.
  • Pin version in composer.json to avoid surprises.

Support

• Developer Onboarding:
  • Pros: Reduces code review friction by standardizing style.
  • Cons: May require education on Broadway’s conventions.
• Troubleshooting:
  • False positives may require rule tweaks (e.g., allowing Laravel’s Route:: prefixes).
  • Limited community support (3 stars, niche use case).

Scaling

• No Scaling Impact:
  • Runs locally in IDE or CI; no server-side overhead.
• Team Adoption:
  • Easier for small/medium teams than large orgs with diverse conventions.
  • May slow down PRs if rules are too strict.

Failure Modes

Ramp-Up

• Time to Value:
  • Immediate: Can be added to CI in <1 hour.
  • Full Enforcement: 1–2 weeks (education + rule tuning).
• Key Stakeholders:
  • Developers: Must adapt to new rules (training needed).
  • PM/Tech Leads: Decide enforcement policy (blocking vs. warning).
  • Architects: Ensure alignment with Broadway’s design (if used).
• Success Metrics:
  • Reduction in code review time (consistent style).
  • Fewer style-related bugs in event-sourcing logic.
  • CI pass rate for coding standard checks.