Code Standard Laravel Package

Technical Evaluation

Architecture Fit

• Code Quality Layer: Acts as a static analysis layer complementary to Laravel’s existing tooling (e.g., Pest, PHPUnit, Laravel Telescope). Integrates natively with PHP_CodeSniffer, a battle-tested standard for PHP projects, ensuring low architectural friction.
• Laravel-Specific Synergy: Designed for Laravel’s ecosystem (e.g., Blade templates, Eloquent, Route conventions), reducing context-switching for developers familiar with Laravel’s idioms. Aligns with Laravel’s PSR-12 baseline but adds domain-specific rules (e.g., Route::prefix() usage).
• CI/CD Plug-and-Play: Fits seamlessly into GitHub Actions, GitLab CI, or CircleCI as a pre-merge gate, leveraging existing composer scripts (e.g., composer cs-check) without requiring new infrastructure.
• Developer Tooling: Supports IDE integration (PHPStorm, VSCode) and pre-commit hooks, reducing manual review cycles and onboarding time.

Integration Feasibility

• Toolchain Compatibility:
  • PHP_CodeSniffer: Requires v6.x+ (widely adopted in Laravel projects).
  • PHP-CS-Fixer/Laravel Pint: Can enforce formatting rules in parallel with linting.
  • Psalm/PHPStan: No direct conflict, but rules may overlap (e.g., type hints). Mitigation: Use phpstan.neon to exclude files already covered by CodeSniffer.
• Laravel-Specific Quirks:
  • Blade Templates: May need custom rules for .blade.php files (e.g., @foreach syntax).
  • Artisan Commands: Rules for handle() method signatures or signature() usage.
  • Service Providers: Enforce consistent register()/boot() method ordering.
• Database/ORM: No impact, but migration files (.php) will be scanned for consistency.

Technical Risk

• Rule Overlap:
  • PSR-12 vs. Custom Rules: Risk of conflicting severity levels (e.g., PSR-12 treats camelCase as error, but custom rules might enforce snake_case).
  • Mitigation: Run phpcs with both standards and merge rules in .phpcs.xml:

    <rule ref="PSR12">
        <exclude name="Classes.Methods.CamelCapsMethodName"/>
    </rule>
    

• Performance:
  • Large Codebases: Analysis time may slow CI. Mitigation: Use --parallel flag or cache results (e.g., GitHub Actions artifact caching).
  • False Positives: Custom rules may flag legitimate patterns. Mitigation: Test against legacy code before enforcement.
• Maintenance Debt:
  • Unmaintained Package: Low stars/dependents suggest forking may be necessary. Mitigation: Contribute fixes or pin to a stable version.

Key Questions

1. Standard Alignment:
   • Does this replace PSR-12, or is it additive? How are conflicts resolved?
   • Example: Should Route::get() use snake_case or camelCase route names?
2. Rule Granularity:
   • Are rules project-specific (e.g., "always use str()") or generic (e.g., "no trailing whitespace")?
   • Will they break existing code in legacy modules?
3. Toolchain Maturity:
   • Is the package tested with Laravel 10+? Are there known issues with:
     • Laravel Mix (if using Blade rules)?
     • Livewire components?
4. Adoption Barriers:
   • Will developers disable the linter to bypass rules? How will enforcement be culturally adopted?
   • Is there buy-in from senior engineers to enforce it strictly?

Integration Approach

Stack Fit

• Laravel Ecosystem:
  • PHP-CS-Fixer/Laravel Pint: Use as a formatting layer alongside CodeSniffer for linting.
  • GitHub Actions: Add as a required check in PR templates:

    - name: PHP_CodeSniffer
      run: composer cs-check
    

  • IDE: Configure PHPStorm to use this standard for real-time feedback (Settings > Editor > Inspections > PHP > Code Sniffer).
• Non-Laravel PHP: Works anywhere PHP_CodeSniffer is supported (e.g., Symfony, WordPress), but Laravel-specific rules will need exclusion.

Migration Path

1. Assessment Phase (Week 1):
   • Run composer require --dev sandfox.dev/code-standard and test on a non-critical branch:

     ./vendor/bin/phpcs --standard=SandfoxDev/CodeStandard --report=full src/
     

   • Compare output with PSR-12 to identify conflicts.
2. Pilot Phase (Week 2):
   • Enforce selectively (e.g., only in app/Http/Controllers/):

     <!-- .phpcs.xml -->
     <arg name="directory" value="app/Http/Controllers" />
     

   • Use --ignore for known legacy violations:

     ./vendor/bin/phpcs --standard=SandfoxDev/CodeStandard --ignore=app/OldModule
     

3. Full Adoption (Week 3+):
   • Update .phpcs.xml to include the standard globally:

     <config name="standard" value="SandfoxDev/CodeStandard"/>
     

   • Add to CI as a blocking check (fail PRs on errors).

Compatibility

• PHP Version: Verify support for PHP 8.0+ (Laravel 9/10 requirement).
• CodeSniffer Version: Ensure compatibility with squizlabs/php_codesniffer:^6.0.
• Rule Overrides:
  • Use .phpcs.xml to exclude or adjust severity for specific rules:

    <rule ref="SandfoxDev/CodeStandard.Methods.CamelCaps">
        <severity>warning</severity>
    </rule>
    

  • Laravel-Specific Exclusions:

    <file>app/Providers/AppServiceProvider.php</file>
    <exclude name="SandfoxDev/CodeStandard.Providers.RegisterMethodFirst"/>
    

Sequencing

1. Local Development:
   • Integrate into pre-commit hooks (e.g., Husky) before CI.
   • Example .husky/pre-commit:

     #!/bin/sh
     ./vendor/bin/phpcs --standard=SandfoxDev/CodeStandard --warning-severity=3
     

2. CI/CD:
   • Start with warnings-only, then enforce as errors after 2 weeks.
   • Example GitHub Actions:

     - name: PHP_CodeSniffer (Warnings)
       if: github.event_name == 'pull_request'
       run: composer cs-check --warning-severity=3
     

3. Documentation:
   • Publish a team wiki with:
     • Common violations and fixes.
     • Exclusion rationale (e.g., "Why we ignore AppServiceProvider.php for register() order").

Operational Impact

Maintenance

• Rule Updates:
  • Monitor forks (e.g., sandfox-dev/code-standard) if the original package stagnates.
  • Pin versions in composer.json to avoid breaking changes:

    "sandfox.dev/code-standard": "1.0.0"
    

• Dependency Management:
  • Update PHP_CodeSniffer and PHP-CS-Fixer annually to patch vulnerabilities.
  • Example composer.json:

    "require-dev": {
        "squizlabs/php_codesniffer": "^6.0",
        "friendsofphp/php-cs-fixer": "^3.0"
    }
    

Support

• Onboarding:
  • Cheat Sheet: Document top 10 violations and fixes (e.g., "Use str() instead of strlen()").
  • Example:

    Violation	Fix
    Methods.CamelCapsMethodName	getUserData() → getUserData() (or get_user_data() if enforced)
    Controllers.RoutePrefix	Route::prefix('admin') → Route::prefix('admin/')

• IDE Configuration:
  • PHPStorm: Enable real-time inspection (Settings > Editor > Inspections > PHP > Code Sniffer).
  • VSCode: Use PHP Intelephense with:

    "intele