Coding Standard Laravel Package

Technical Evaluation

Architecture Fit

• Pros:
  • Aligns with PSR-1/PSR-2 standards, ensuring consistency with Laravel’s existing PHP-FIG compliance.
  • Lightweight (no runtime dependencies beyond PHP-CS-Fixer/PhpCS) and MIT-licensed, reducing legal/integration friction.
  • Ruleset-based configuration integrates seamlessly with PHP-CS-Fixer or PHP_CodeSniffer, tools already used in Laravel ecosystems.
• Cons:
  • Stale (last release in 2019) may lack modern PHP 8.x/9.x support or Laravel-specific rules (e.g., Blade template conventions).
  • Minimal adoption (0 dependents) suggests niche or abandoned use; may require customization for Laravel’s unique patterns (e.g., Facades, Eloquent).

Integration Feasibility

• Low Effort:
  • Drop-in replacement for existing PSR-1/PSR-2 rulesets in CI/CD pipelines (e.g., GitHub Actions, GitLab CI).
  • Can be layered alongside other standards (e.g., friendsofphp/php-cs-fixer) via custom ruleset composition.
• High Effort:
  • May need forking to add Laravel-specific rules (e.g., Facade naming, Blade syntax) or PHP 8.x fixes.
  • Requires validation against Laravel’s internal coding standards (e.g., Laravel Framework’s own PSR extensions).

Technical Risk

• Critical:
  • Compatibility: Untested with PHP 8.x+ features (e.g., named arguments, match expressions) or Laravel’s modern syntax.
  • Maintenance: No active development; bug fixes or updates must be community-driven.
• Moderate:
  • Performance: Ruleset overhead negligible, but custom rules could introduce CI slowdowns.
  • Tooling: Assumes PHP-CS-Fixer/PhpCS is already in use; may require setup for teams using alternative tools (e.g., Psalm).
• Low:
  • No breaking changes expected for basic PSR compliance.

Key Questions

1. Does this replace or supplement existing standards?
   • Compare against Laravel’s default .php-cs-fixer.dist.php or phpcs.xml.
2. Are there Laravel-specific gaps?
   • E.g., does it enforce Facade naming (App\Services\*), Blade indentation, or Eloquent method chaining?
3. How will PHP 8.x+ features be handled?
   • Test against a Laravel 10.x project to identify rule failures.
4. What’s the migration path?
   • Can it coexist with existing tools, or require a full rewrite of rulesets?
5. Who maintains this?
   • Sunrise’s GitHub activity is dormant; is there a backup plan for critical fixes?

Integration Approach

Stack Fit

• Compatibility:
  • PHP-CS-Fixer: Works as a custom ruleset (see README example).
  • PHP_CodeSniffer: Requires phpcs.xml configuration (same as above).
  • Laravel: No native integration, but can be bolted into:
    • CI pipelines (e.g., php-cs-fixer fix --rules=./vendor/sunrise/coding-standard/ruleset.xml).
    • Pre-commit hooks (via laravel-pint or custom scripts).
    • IDE plugins (PHPStorm/VSCode via PhpCS integration).
• Conflicts:
  • May clash with Laravel’s default Pint/PHP-CS-Fixer config if rules differ (e.g., line length, brace positioning).

Migration Path

1. Assessment Phase:
   • Run against a sample Laravel project to identify rule conflicts/errors.
   • Compare output with Laravel’s default standards (e.g., vendor/bin/php-cs-fixer fix).
2. Pilot Integration:
   • Add as a secondary ruleset in CI (e.g., GitHub Actions):

     - name: Sunrise Coding Standard
       run: vendor/bin/php-cs-fixer fix --rules=./vendor/sunrise/coding-standard/ruleset.xml --dry-run
     

   • Use --allow-risky=yes cautiously for PHP 8.x compatibility.
3. Customization (if needed):
   • Fork the repo to add Laravel-specific rules (e.g., Blade template checks).
   • Extend ruleset.xml to include/exclude specific files (e.g., ignore resources/views if Blade rules are missing).
4. Full Adoption:
   • Replace or merge with existing tools (e.g., update .php-cs-fixer.dist.php to include Sunrise rules).
   • Document deviations from Laravel’s defaults in team guidelines.

Compatibility

Sequencing

1. Phase 1: Validate against a non-critical branch (e.g., feature/x).
2. Phase 2: Gradually enforce in CI (start with warnings, then failures).
3. Phase 3: Customize rules for Laravel-specific needs (if Phase 1 reveals gaps).
4. Phase 4: Deprecate old standards in favor of Sunrise (if adopted).

Operational Impact

Maintenance

• Pros:
  • No runtime overhead: Rulesets are static; no server-side maintenance.
  • Composer-managed: Updates via composer update (though risky due to staleness).
• Cons:
  • No active maintenance: Bugs or PHP version issues require community patches.
  • Customization debt: Forking adds long-term maintenance burden.
• Mitigations:
  • Pin to 1.0.0 in composer.json to avoid accidental updates.
  • Monitor for forks (e.g., sunrise-php/coding-standard-laravel) or alternatives.

Support

• Internal:
  • Team must document deviations from Laravel’s defaults (e.g., "Sunrise enforces 120 chars, but Laravel Pint uses 80").
  • Onboard developers to new rules via:
    • Interactive tutorials (e.g., "Why we use Sunrise").
    • IDE plugins (PHPStorm snippets for common fixes).
• External:
  • Limited community support; rely on:
    • GitHub issues (if any activity).
    • PHP-CS-Fixer/PhpCS documentation for troubleshooting.

Scaling

• Performance:
  • Minimal impact on CI/CD; rulesets are lightweight.
  • Risk: Custom rules or large codebases may slow down analysis.
• Team Adoption:
  • Resistance: Developers may prefer Laravel’s native tools (Pint).
  • Buy-in: Highlight benefits (e.g., "Sunrise enforces stricter PSR-2 than Pint").
• Tooling:
  • Scales with existing PHP-CS-Fixer/PhpCS infrastructure.
  • Challenge: Integrating with monorepos or microservices may require per-project config.

Failure Modes

Ramp-Up

• Onboarding Time: Low to Medium
  • Developers: 1–2 hours to understand new rules (if documented).
  • Engineering: 1–2 days to integrate into CI and validate.
• Key Activities:
  1. Training: Run a workshop on Sunrise vs. Laravel’s defaults.
  2. Pilot: Enforce in a single repo before company-wide rollout.
  3. Feedback Loop: Gather input on false positives/negatives.
• Blockers:
  • Lack of Laravel-specific documentation.
  • Resistance to "yet another tool" without clear ROI.