Coding Standard Laravel Package

Technical Evaluation

Architecture Fit

• Laravel Compatibility: The package integrates seamlessly with Laravel as it extends PHP_CodeSniffer, a widely adopted tool in PHP ecosystems. Laravel’s existing PHP_CodeSniffer integration (via php-cs-fixer or standalone) ensures minimal architectural disruption.
• Static Analysis Alignment: Complements Laravel’s PSR-12 and PHPStan adoption, reinforcing consistency in code quality checks.
• Non-Invasive: Operates as a pre-commit hook or CI/CD gate without modifying core Laravel logic.

Integration Feasibility

• Low Coupling: No direct Laravel framework dependencies; integrates via PHP_CodeSniffer CLI or Composer.
• Toolchain Synergy: Works alongside:
  • PHPStan (type safety)
  • Pint/PHP-CS-Fixer (auto-formatting)
  • Psalm (static analysis)
• Automation-Friendly: Supports Git hooks, GitHub Actions, or CI pipelines (e.g., GitLab CI) with minimal setup.

Technical Risk

• False Positives/Negatives: Some sniffs (e.g., DisallowNullSafeObjectOperator) may conflict with Laravel’s dynamic property access (e.g., $request->input()). Requires custom configuration or exclusions.
• Performance Overhead: Running ~100 sniffs on large codebases (e.g., 50K+ LOC) may slow CI/CD. Mitigate via parallel execution or selective sniff subsets.
• Maintenance Burden: Requires ongoing tuning as Laravel evolves (e.g., new attribute syntax in PHP 8.0+).

Key Questions

1. Sniff Selection: Which categories (functional/cleaning/formatting) align with team priorities? Example: Disable DisallowNullSafeObjectOperator if Laravel’s dynamic features are critical.
2. Automation Strategy:
   • Pre-commit (local dev) vs. CI-only?
   • Block builds on failures or treat as warnings?
3. Conflict Resolution:
   • How to handle false positives (e.g., legacy code, third-party libraries)?
   • Tooling for whitelisting or per-file exclusions?
4. Performance:
   • Benchmark impact on CI runtime (e.g., 10M LOC vs. 10K LOC).
   • Cache results (e.g., phpcs --cache)?
5. Team Adoption:
   • Training needed for auto-fixable sniffs (e.g., Arrays.TrailingArrayComma)?
   • Alignment with existing style guides (e.g., Laravel’s default PSR-12)?

Integration Approach

Stack Fit

• Primary Tools:
  • PHP_CodeSniffer (base layer)
  • Composer (dependency management)
  • Git Hooks (pre-commit) or CI (GitHub Actions/GitLab CI)
• Secondary Tools:
  • PHP-CS-Fixer (for auto-formatting conflicts)
  • PHPStan (for type safety conflicts)
• Laravel-Specific:
  • Exclude vendor/ and config/ paths to avoid false positives in framework files.
  • Customize sniffs for Laravel patterns (e.g., allow nullsafe in service containers).

Migration Path

1. Phase 1: Audit
   • Run phpcs with all sniffs to identify violations.
   • Prioritize auto-fixable sniffs (e.g., formatting) for immediate wins.
2. Phase 2: Incremental Enforcement
   • Start with non-breaking sniffs (e.g., Arrays.TrailingArrayComma).
   • Gradually introduce functional sniffs (e.g., Classes.DisallowConstructorPropertyPromotion).
3. Phase 3: Automation
   • Integrate into CI (fail builds on violations).
   • Add pre-commit hooks (e.g., via husky + simple-phpunit).
4. Phase 4: Optimization
   • Cache results (--cache) for CI speed.
   • Use parallel execution (--parallel) for large codebases.

Compatibility

• PHP Version: Supports PHP 8.0+ (Laravel’s LTS range).
• Laravel Version: Tested with Laravel 9+ (PHP 8.0+ features like attributes).
• Dependency Conflicts:
  • Ensure slevomat/coding-standard and php-cs-fixer versions are compatible.
  • Avoid version skew with PHP_CodeSniffer (e.g., squizlabs/php_codesniffer:^3.7).

Sequencing

1. Setup:

   composer require --dev slevomat/coding-standard
   vendor/bin/phpcs --standard=SlevomatCodingStandard run src/
   

2. Configure:
   • Create .php-cs-fixer.dist.php to exclude conflicting sniffs.
   • Example:

     return (new PhpCsFixer\Config())
         ->setRules([
             '@SlevomatCodingStandard' => true,
             'SlevomatCodingStandard.ControlStructures.DisallowNullSafeObjectOperator' => false,
         ]);
     

3. Automate:
   • Add to .github/workflows/php.yml:

     - name: Run Slevomat Coding Standard
       run: vendor/bin/phpcs --standard=SlevomatCodingStandard --error-severity=3 src/
     

Operational Impact

Maintenance

• Configuration Drift: Requires quarterly reviews to update excluded sniffs as Laravel evolves (e.g., new attribute syntax).
• Dependency Updates: Monitor slevomat/coding-standard for breaking changes (e.g., PHP 8.2+ features).
• Toolchain Sync: Ensure compatibility with updated PHP_CodeSniffer or php-cs-fixer.

Support

• Developer Onboarding:
  • Document common exceptions (e.g., "Why is nullsafe allowed in AppServiceProvider?").
  • Provide cheat sheets for auto-fixable sniffs (e.g., Arrays.TrailingArrayComma).
• Incident Response:
  • False positives may require temporary exclusions (track in a SUPPORT.md).
  • Example: Disable Classes.ClassLength for legacy monolithic classes.

Scaling

• Performance:
  • CI Parallelism: Split sniffs by directory (e.g., phpcs --parallel --standard=SlevomatCodingStandard src/Tests/ src/App/).
  • Caching: Use --cache to avoid reprocessing unchanged files.
• Codebase Growth:
  • Selective Enforcement: Disable sniffs for vendor/ and storage/ paths.
  • Incremental Adoption: Start with core app/ directory, expand to modules.

Failure Modes

Ramp-Up

• Team Training:
  • Workshop: Demo auto-fixable sniffs and common pitfalls.
  • Pair Programming: Onboard senior devs to configure exclusions.
• Metrics:
  • Track violation reduction over 3 months.
  • Measure CI runtime before/after optimizations.
• Feedback Loop:
  • Survey devs on pain points (e.g., "Which sniffs are too restrictive?").
  • Adjust configuration based on data (e.g., disable Classes.ClassLength if unused).