Coding Standard Laravel Package

Technical Evaluation

Architecture Fit

• Laravel/PHP Alignment: The package extends PHP_CodeSniffer (PHPCS) with Slevomat’s coding standards, which are natively compatible with Laravel’s PSR-12 baseline. It introduces modular, opinionated rules (e.g., trailing commas, enum ordering) that align with modern PHP (8+) practices, reducing technical debt in Laravel projects.
• Modular Design: Rules are independent (e.g., SlevomatCodingStandard.Arrays.TrailingArrayComma), enabling selective enforcement (e.g., CI-only vs. local dev). This fits Laravel’s plugin-based architecture (e.g., laravel-shift/blueprint for static analysis).
• Dependency Graph: Built on PHPCS 4.0+ and Slevomat’s coding-standard, which are stable but require upstream compatibility checks (e.g., Laravel’s php-cs-fixer or pint may conflict if not coordinated).

Integration Feasibility

• Laravel-Specific Hooks: No native Laravel integration, but can be wrapped in a custom Artisan command or CI script (e.g., GitHub Actions workflow). Example:

  // app/Console/Commands/RunCodingStandard.php
  use Spaze\CodingStandard\Sniffs\AllSniffs;
  phpcs(['--standard=./vendor/spaze/coding-standard/ruleset.xml', '--extensions=php', 'app/']);
  

• PHPCS Configuration: Requires .phpcs.xml customization to:
  • Extend base rules (e.g., PSR12 + Slevomat).
  • Exclude vendor/legacy code (e.g., <exclude-pattern>*/vendor/*</exclude-pattern>).
• Toolchain Compatibility:
  • Works with: PHPCS, Laravel Forge/Envoyer, GitHub Actions.
  • Conflicts with: laravel-pint (formatting) or rector (refactoring) if rules overlap (e.g., brace spacing).

Technical Risk

• PHPCS 4.0 Migration:
  • Risk: Laravel projects using PHPCS <4.0 may fail due to breaking changes (e.g., error code renaming).
  • Mitigation: Audit phpcs.xml and update error codes (see PHPCS 4.0 Upgrade Guide).
• Rule Overlap:
  • Risk: Conflicts with PSR-12 (e.g., SpacingAfterBlock) or custom PHPCS rules.
  • Mitigation: Run dry tests with --report=full to identify conflicts before enforcement.
• Performance:
  • Risk: PHPCS can slow CI if not optimized (e.g., large codebase, no caching).
  • Mitigation: Use parallel execution (--parallel) and cache results (e.g., GitHub Actions cache).

Key Questions

1. PHPCS Adoption:
   • Is PHPCS already used in the stack? If not, what’s the alternative static analysis tool (e.g., Psalm, PHPStan)?
2. Rule Prioritization:
   • Should rules be phased in (e.g., start with Arrays.TrailingComma in CI, then expand)?
3. CI/CD Integration:
   • How will violations be handled (e.g., fail builds, annotate PRs, or log only)?
4. Legacy Code:
   • Are there exceptions for older Laravel versions (e.g., PHP 7.3) or third-party packages?
5. Toolchain Synergy:
   • Will this replace or complement existing tools (e.g., laravel-pint, rector)?

Integration Approach

Stack Fit

• Primary Integration Points:
  • CI/CD Pipelines: Run PHPCS as a pre-commit or PR check (e.g., GitHub Actions, GitLab CI).
  • Local Development: Integrate with PHPStorm (native PHPCS support) or VSCode (via extensions like PHP Intelephense).
  • Laravel Artisan: Wrap PHPCS in a custom command for ad-hoc checks (e.g., php artisan coding-standard:check).
• Complementary Tools:
  • Formatting: Use laravel-pint for auto-fixing (e.g., trailing commas) while PHPCS enforces semantic rules (e.g., Yoda comparisons).
  • Static Analysis: Pair with PHPStan or Psalm for type safety (this package focuses on style/format).

Migration Path

1. Assessment Phase:
   • Audit existing phpcs.xml (if any) and baseline violations.
   • Identify conflicting rules (e.g., PSR-12 vs. Slevomat).
2. PHPCS Upgrade:
   • Update to PHPCS 4.0+ (composer require --dev squizlabs/php_codesniffer:^4.0).
   • Migrate error codes (e.g., PSR12.Files.FileHeader.SpacingAfterBlock → modular rules).
3. Incremental Rollout:
   • Phase 1: Enforce non-breaking rules (e.g., trailing commas) in CI.
   • Phase 2: Add strict rules (e.g., enum ordering) with opt-outs for legacy code.
4. Toolchain Sync:
   • Configure laravel-pint to auto-fix PHPCS-compatible formatting (e.g., brace spacing).
   • Update CI workflows to run PHPCS after tests but before deployment.

Compatibility

• Laravel Versions:
  • Supported: Laravel 8+ (PHP 7.4+).
  • Legacy: Laravel <8 may require rule exclusions or PHPCS 3.x (not recommended).
• PHP Extensions:
  • Requires PHP 7.4+ (aligned with Laravel 8+).
  • No hard dependencies on Laravel core (pure PHPCS rules).
• Third-Party Conflicts:
  • Risk: Some vendor packages may violate rules (e.g., laravel/framework).
  • Mitigation: Exclude vendor/ in .phpcs.xml or whitelist exceptions.

Sequencing

1. Pre-requisites:
   • Install PHPCS and Slevomat’s base standard:

     composer require --dev squizlabs/php_codesniffer slevomat/coding-standard
     

   • Install the target package:

     composer require --dev spaze/coding-standard
     

2. Configuration:
   • Create/extend .phpcs.xml:

     <config name="installed_paths" value="./vendor/spaze/coding-standard,ruleset.xml"/>
     <rule ref="SlevomatCodingStandard"/>
     <exclude-pattern>*/vendor/*</exclude-pattern>
     

3. Testing:
   • Run PHPCS on a subset of files (e.g., app/Http/):

     phpcs --standard=./vendor/spaze/coding-standard/ruleset.xml app/Http/
     

4. CI Integration:
   • Add to GitHub Actions (.github/workflows/phpcs.yml):

     - name: Run PHPCS
       run: phpcs --standard=./vendor/spaze/coding-standard/ruleset.xml --report=full --warning-severity=3 --error-severity=5
     

Operational Impact

Maintenance

• Low Effort:
  • No custom rules to maintain (built on Slevomat’s standards).
  • Updates: Sync with spaze/coding-standard releases (e.g., composer update spaze/coding-standard).
• Deprecation Risk:
  • If spaze/coding-standard is abandoned, migrate to Slevomat’s direct rules (slevomat/coding-standard).

Support

• Troubleshooting:
  • Common Issues:
    • False positives (e.g., legacy code violations).
    • PHPCS configuration errors (e.g., missing installed_paths).
  • Debugging Tools:
    • --report=full for detailed violations.
    • --diff to compare against a clean baseline.
• Community:
  • Limited Activity: 2 stars, but Slevomat’s standards are actively maintained.
  • Fallback: Use Slevomat’s direct rules if issues arise.

Scaling

• Performance:
  • **Large Codebases