Php Coding Standard Laravel Package

Technical Evaluation

Architecture Fit

• Laravel Compatibility: The package is built on EasyCodingStandard (ECS), a widely adopted PHP coding standards tool. Laravel projects can leverage this for consistent code quality enforcement without requiring major architectural changes.
• Rule Customization: The package provides predefined configurations (Symfony, WordPress, common PHP) but allows customization via ecs.php, making it adaptable to Laravel’s PSR-12 and framework-specific conventions.
• Static Analysis: Since it’s a linter, it integrates well with Laravel’s CI/CD pipelines (e.g., GitHub Actions, GitLab CI) for pre-commit checks.

Integration Feasibility

• Low-Coupling: The package is standalone and doesn’t modify Laravel’s core. It runs as a command-line tool (vendor/bin/ecs), making integration straightforward.
• Dependency Overhead: Minimal—only requires ECS and its dependencies (no Laravel-specific packages).
• CI/CD Integration: Can be gated in PRs (fail builds on violations) or run locally via IDE plugins (PHPStorm, VSCode).

Technical Risk

• Rule Conflicts: Laravel’s PSR-12 and framework-specific patterns (e.g., Facades, Blade templates) may conflict with some rules. Requires customization (e.g., skipping UnusedVariableSniff for Blade files).
• Performance: Running on large codebases (e.g., monorepos) could slow CI pipelines. Mitigation: Parallelize checks or cache results.
• Maintenance Burden: If the package stagnates (last release: 2023-06-29), the TPM must fork or migrate to another standard (e.g., php-cs-fixer).

Key Questions

1. Does Laravel’s codebase align with the provided configs (whatwedo-symfony.php, whatwedo-common.php)?
   • If not, how much customization is needed?
2. How will violations be handled?
   • Autofix (ECS supports this) vs. manual review?
3. CI/CD Strategy:
   • Should this block merges or run as a post-commit check?
4. Tooling Integration:
   • Will IDEs (PHPStorm) or Git hooks enforce this?
5. Long-Term Viability:
   • Is the package actively maintained, or should we consider alternatives (e.g., rector/rector)?

Integration Approach

Stack Fit

• Laravel Ecosystem: Works seamlessly with:
  • Composer (installation via require).
  • PHPUnit (can integrate as a pre-test hook).
  • Laravel Mix/Vite (for frontend checks, if extended).
• Tooling Synergy:
  • PHPStorm: Supports ECS via Inspection Profiles.
  • VSCode: Extensions like PHP Intelephense can integrate linters.
  • Git Hooks: Pre-commit checks via husky or pre-commit.

Migration Path

1. Pilot Phase:
   • Run locally on a subset of the codebase (e.g., app/ directory).
   • Compare results with existing standards (e.g., PSR-12).
2. Configuration Alignment:
   • Start with whatwedo-common.php, then customize ecs.php for Laravel-specific rules.
   • Example:

     $ecsConfig->skip([
         // Skip Blade-specific unused vars
         __DIR__.'/resources/views/**',
     ]);
     

3. CI/CD Rollout:
   • Add to GitHub Actions as a required check:

     - name: Run PHP Coding Standard
       run: vendor/bin/ecs check src --config=ecs.php
     

4. Autofix Enablement:
   • Gradually introduce --fix flag for non-breaking changes.

Compatibility

• PHP Version: Requires PHP 8.0+ (check Laravel’s minimum version).
• Laravel-Specific Files:
  • Blade templates (*.blade.php) may need exclusions.
  • Migrations/Seeds might require custom rules (e.g., allow DB::table() style).
• Third-Party Packages:
  • Vendor code (e.g., node_modules for Laravel Mix) should be excluded.

Sequencing

1. Phase 1 (0-2 weeks):
   • Install and baseline current violations.
   • Document custom rules needed.
2. Phase 2 (2-4 weeks):
   • Integrate into CI/CD (block merges on critical violations).
   • Train devs on common fixes.
3. Phase 3 (Ongoing):
   • Expand to all directories (e.g., database/, routes/).
   • Add autofix for safe violations.

Operational Impact

Maintenance

• Rule Updates:
  • Monitor ECS/Symplify updates for breaking changes.
  • Fork the package if maintenance stops (low risk due to MIT license).
• Custom Config Drift:
  • Document why rules are skipped/modified in ecs.php.
  • Use version control to track changes.

Support

• Developer Onboarding:
  • Add docs on how to read violation messages and apply fixes.
  • Example:

    "Error: Line exceeds 120 chars. Fix with vendor/bin/ecs fix --dry-run."

• Tooling Support:
  • Provide IDE templates for common fixes (e.g., PSR-12 alignment).
  • Slack/Teams bot to notify teams of violations (via CI status).

Scaling

• Performance:
  • For large repos, use --parallel flag or split checks (e.g., app/ vs. tests/).
  • Cache results in CI (e.g., GitHub Actions cache).
• Team Adoption:
  • Start with mandatory checks for new PRs, then expand.
  • Gamify compliance (e.g., "Zero Violations" badge in PRs).

Failure Modes

Ramp-Up

• Training:
  • Workshop: Demo ECS, show before/after fixes.
  • Cheat Sheet: Common commands (check, fix, skip).
• Metrics:
  • Track violation trends (e.g., "Reduced violations by 30% in 2 months").
  • DORA Metrics: Measure developer velocity post-adoption.
• Feedback Loop:
  • Quarterly review of rules (are they too strict/lenient?).
  • Anonymous surveys to gauge pain points.