Coding Standard Laravel Package

Technical Evaluation

Architecture Fit

• Code Quality Enforcement: The package integrates seamlessly with Laravel’s PHP-based stack, providing static analysis for enforcing consistent, maintainable, and secure code standards. It complements Laravel’s existing tooling (e.g., PHPStan, Psalm) by focusing on sniff-level checks (formatting, functional safety, and dead code detection).
• Complementarity with Laravel Ecosystem:
  • Works alongside PHP_CodeSniffer (already used in Laravel via php-cs-fixer or custom sniffs).
  • Aligns with Laravel’s PSR-12 adherence but extends it with Slevomat-specific rules (e.g., array sorting, attribute formatting, cognitive complexity).
  • Supports automatic fixes (e.g., 🔧 sniffs), reducing manual refactoring effort.
• Non-Invasive: Operates as a pre-commit hook or CI gate without modifying core Laravel logic.

Integration Feasibility

• Low Coupling: Can be integrated via Composer (slevomat/coding-standard) and configured in phpcs.xml without Laravel-specific modifications.
• Toolchain Compatibility:
  • Works with PHP_CodeSniffer (v3.6+), which Laravel projects already use for PSR checks.
  • Supports parallel execution (via --parallel flag) for large codebases.
  • Integrates with GitHub Actions, GitLab CI, or Laravel Forge for automated enforcement.
• Customization: Rules can be whitelisted/blacklisted per project or team preferences.

Technical Risk

Key Questions for TPM

1. Prioritization:
   • Should we enforce all Slevomat rules, or start with a subset (e.g., formatting + safety)?
   • Which rules conflict with existing php-cs-fixer configurations?
2. Toolchain Integration:
   • Should this replace, complement, or run alongside php-cs-fixer?
   • How will we handle automatic fixes in PRs (e.g., GitHub Actions auto-commit)?
3. Onboarding:
   • What training is needed for devs to understand why certain rules exist (e.g., DisallowYodaComparison)?
4. Legacy Code:
   • How will we handle existing violations in the codebase? (Gradual enforcement?)
5. Scaling:
   • Will we need to parallelize checks for monorepos or large modules?

Integration Approach

Stack Fit

• Primary Tools:
  • PHP_CodeSniffer (v3.6+): Core engine for running sniffs.
  • Composer: Dependency management (slevomat/coding-standard + squizlabs/php_codesniffer).
  • PHP-CS-Fixer: For automated formatting (can run alongside Slevomat).
• Laravel-Specific:
  • Laravel Envoy or Deployer: For remote execution in CI/CD.
  • Laravel Forge: Pre-configure sniffs in server-level hooks.
• CI/CD:
  • GitHub Actions: Dedicated workflow for Slevomat checks.
  • Parallel Testing: Split checks by module (e.g., app/, packages/) to reduce runtime.

Migration Path

Compatibility

• PHP Version: Requires PHP 8.0+ (aligns with Laravel 9+/10+).
• Laravel Version: No direct dependency, but Laravel Valet/Sail can run phpcs natively.
• Existing Sniffs:
  • Conflict Risk: Rules like Arrays.AlphabeticallySortedByKeys may clash with php-cs-fixer’s array formatting.
  • Solution: Use phpcs --ignore=SlevomatCodingStandard.Arrays.* for overlapping rules.

Sequencing

1. Pre-CI Check:
   • Run in developer environments (e.g., make lint) to catch issues early.
2. CI Validation:
   • GitHub Actions:

     - name: Run Slevomat Coding Standard
       run: vendor/bin/phpcs --standard=Slevomat --report=emacs --error-severity=1
     

3. Post-Merge:
   • Autofix enabled for formatting rules (e.g., Arrays.TrailingArrayComma).
   • Slack Notifications for critical violations (e.g., Classes.ForbiddenPublicProperty).

Operational Impact

Maintenance

• Rule Updates:
  • Automated: Use composer update slevomat/coding-standard in CI to test new rules.
  • Deprecation: Monitor Laravel’s PHPStan rules for overlapping deprecations (e.g., DisallowNullSafeObjectOperator).
• Custom Rulesets:
  • Maintain a ruleset.xml in the repo to override defaults (e.g., disable Classes.ClassLength).
  • Example:

    <rule ref="SlevomatCodingStandard">
        <exclude name="SlevomatCodingStandard.Classes.ClassLength"/>
        <config name="SlevomatCodingStandard.Arrays.AlphabeticallySortedByKeys" value="true"/>
    </rule>
    

Support

• Developer Onboarding:
  • Documentation: Add a CODE_STANDARD.md with:
    • Why rules exist (e.g., "Yoda conditions reduce readability").
    • How to suppress rules locally (// phpcs:ignore).
  • Workshops: 30-minute session on common violations and fixes.
• Escalation Path:
  • Severity 1: Blocking CI failures (e.g., DisallowNullSafeObjectOperator).
  • Severity 2: Non-blocking but requires review (e.g., Arrays.AlphabeticallySortedByKeys).

Scaling

• Performance:
  • Large Codebases: Use --parallel=8 to distribute checks across CPU cores.
  • Exclusions: Skip vendor/ and node_modules/ via .phpcs.exclude.
• Distributed Teams:
  • Local vs. CI: Allow local overrides (e.g., phpcs --config=local.ruleset.xml) for WIP code.
  • Federated Enforcement: Use GitHub Code Scanning for org-wide compliance.

Failure Modes

Ramp-Up

• Timeline:
  • Week 1: Assessment + pilot module.
  • Week 2: CI integration + team training.
  • Week 4: Full enforcement with opt-out