Coding Standard Laravel Package

Technical Evaluation

Architecture Fit

• Custom Coding Standard: The package is a PHP_CodeSniffer standard (built on top of squizlabs/php_codesniffer, slevomat/coding-standard, and doctrine/coding-standard), meaning it enforces custom linting rules rather than core Laravel functionality. It is not a Laravel-specific package but can be integrated into any PHP/Laravel project to enforce consistent coding style.
• Rule Customization: The standard appears to be opinionated (e.g., dropping @api annotations, PHP 8.4 support). A TPM must evaluate whether these rules align with the team’s existing standards (e.g., PSR-12, custom in-house rules).
• Extensibility: Since it’s built on PHP_CodeSniffer, it can be extended or overridden via custom sniffs or configuration, making it adaptable to Laravel-specific needs (e.g., Blade template rules).

Integration Feasibility

• Low Coupling: The package does not modify Laravel’s core—it only adds static analysis via phpcs. Integration is non-intrusive and can run in CI/CD pipelines or locally via CLI.
• Dependency Conflicts: Potential conflicts with existing phpcs setups (e.g., if the team already uses psalm or phpstan with custom rules). A TPM should audit existing tooling.
• PHP Version Support: Requires PHP 8.2+ (as of v2.15.0). If the Laravel project uses PHP 8.1 or lower, this may require a PHP upgrade or a forked version.

Technical Risk

• False Positives/Negatives: Custom rules (e.g., @api annotation bans) may flag legitimate code or miss issues. Requires manual review during adoption.
• Maintenance Overhead: Since the package is lightly maintained (last release in 2026, but with no active issues), long-term support is a risk. A TPM should plan for forking or migrating if maintenance stalls.
• Performance Impact: Running phpcs in CI/CD adds execution time. For large codebases, this could slow down pipelines if not optimized (e.g., parallel runs, caching).

Key Questions

1. Alignment with Existing Standards:
   • Does this standard replace, supplement, or conflict with current PSR-12, custom rules, or tools like phpstan?
   • Are there Laravel-specific rules (e.g., Blade syntax, Facade usage) missing?
2. Adoption Strategy:
   • Should this be mandatory for all PRs or optional for teams?
   • How will false positives be handled (e.g., rule exceptions)?
3. Tooling Integration:
   • Can this integrate with existing CI/CD (GitHub Actions, GitLab CI) without breaking workflows?
   • Should it run locally (e.g., via VSCode extension) or only in CI?
4. Long-Term Viability:
   • Is the team willing to fork/maintain if upstream development stops?
   • Are there alternatives (e.g., laravel-pint, deptrac) that better fit Laravel’s needs?
5. Performance:
   • What is the baseline phpcs runtime for the codebase? Will it require optimizations (e.g., caching, parallelism)?

Integration Approach

Stack Fit

• PHP/Laravel Compatibility:
  • Works with any PHP 8.2+ project, including Laravel 9/10.
  • No Laravel-specific dependencies, so integration is framework-agnostic.
• Toolchain Synergy:
  • Complements existing tools like:
    • PHPStan/Psalm (static analysis)
    • Pint (auto-formatting)
    • Dephpend (dependency analysis)
  • Can be chained in CI (e.g., run phpstan → phpcs → tests).
• IDE Support:
  • Integrates with PHPStorm, VSCode (via extensions like "PHP_CodeSniffer"), and PHPMD for real-time feedback.

Migration Path

1. Assessment Phase:
   • Audit existing codebase for current violations (run phpcs locally).
   • Identify conflicting rules (e.g., if the team uses @api annotations).
2. Pilot Phase:
   • Opt-in adoption: Allow teams to self-select into using the standard.
   • Gradual enforcement: Start with warnings in CI, then blocking failures.
3. Integration Steps:
   • Add to composer.json:

     composer require --dev wyrihaximus/coding-standard
     

   • Configure phpcs in phpcs.xml:

     <config defaultStandard="WyriHaximus">
         <arg name="extensions" value="php,blade"/>
     </config>
     

   • CI/CD Setup:
     • Add a step to run ./vendor/bin/phpcs (e.g., in GitHub Actions):

       - name: Run PHP_CodeSniffer
         run: ./vendor/bin/phpcs --standard=WyriHaximus --warning-severity=0 src/
       

4. Laravel-Specific Tweaks:
   • Extend rules for Blade templates (if needed) by creating custom sniffs.
   • Override rules via phpcs.xml (e.g., disable @api checks if used internally).

Compatibility

• Backward Compatibility:
  • Breaking changes exist (e.g., PHP 8.0 dropped in v2.13.0). Ensure the Laravel project’s PHP version is supported.
  • Rule changes (e.g., @api ban) may require codebase updates.
• Conflict Resolution:
  • If the team uses custom phpcs rules, merge them with this standard.
  • Use phpcs --ignore=* to exclude files during transition.

Sequencing

1. Phase 1: Local Adoption (2-4 weeks)
   • Developers install and run phpcs locally.
   • Document common violations and fixes.
2. Phase 2: CI Integration (1-2 weeks)
   • Add to CI as a non-blocking check.
   • Monitor failure rates and adjust rules.
3. Phase 3: Enforcement (1-2 weeks)
   • Switch to blocking failures in CI.
   • Provide developer training on rule rationale.
4. Phase 4: Optimization (Ongoing)
   • Cache phpcs results in CI.
   • Explore parallel execution for large codebases.

Operational Impact

Maintenance

• Dependency Updates:
  • The package auto-updates dependencies (e.g., slevomat/coding-standard), but the main package itself has irregular releases. A TPM should:
    • Monitor for breaking changes in upstream dependencies.
    • Plan for forking if maintenance stops.
• Rule Updates:
  • New rules may be added. The team should review changes and decide whether to adopt them.
• Customization:
  • Overriding rules requires maintaining custom phpcs.xml or sniffs.

Support

• Developer Onboarding:
  • Requires training on:
    • How to read phpcs output.
    • How to request rule exceptions.
  • Documentation gap: The package has minimal README. A TPM should create internal guides.
• Troubleshooting:
  • Common issues:
    • False positives (e.g., legacy @api annotations).
    • Performance bottlenecks in CI.
  • Solutions:
    • Whitelist exceptions in phpcs.xml.
    • Optimize CI runs (e.g., cache dependencies).

Scaling

• Performance:
  • Large codebases: phpcs can be slow. Mitigations:
    • Parallel execution (e.g., phpcs --parallel).
    • Incremental analysis (only changed files in PRs).
    • CI caching (e.g., GitHub Actions cache for vendor/).
  • Blade templates: If analyzing Blade files, ensure the file extension is included (--extensions=php,blade).
• Team Growth:
  • New developers must adopt the standard quickly. Automate checks in pre-commit hooks (e.g., husky + phpcs).
  • Cross-team consistency: Enforce the same standard across multiple repos.

Failure Modes