Php Coding Standard Laravel Package

Getting Started

Minimal Setup

1. Install the package in your Laravel project:

   composer require whatwedo/php-coding-standard --dev
   

2. Run a basic check against your Laravel app (e.g., app/ directory) using the Symfony preset:

   vendor/bin/ecs check app/ --config vendor/whatwedo/php-coding-standard/config/whatwedo-symfony.php
   

   • For WordPress projects (unlikely in Laravel but included for completeness), use whatwedo-wordpress.php.
   • For generic PHP projects, use whatwedo-common.php.

3. Fix automatically (if using ecs ≥ v9.0):

   vendor/bin/ecs fix app/ --config vendor/whatwedo/php-coding-standard/config/whatwedo-symfony.php
   

First Use Case: Pre-Commit Hook

Integrate into your workflow via a Git pre-commit hook (e.g., using pre-commit):

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: php-coding-standard
        name: PHP Coding Standard
        entry: vendor/bin/ecs check app/ --config vendor/whatwedo/php-coding-standard/config/whatwedo-symfony.php
        language: system
        pass_filenames: false
        stages: [commit]

Implementation Patterns

Workflow Integration

1. Laravel-Specific Customization Extend the Symfony preset (whatwedo-symfony.php) in your project’s ecs.php to:

   • Skip Laravel-specific files (e.g., generated migrations, cached views):

     $ecsConfig->skip([
         __DIR__.'/../database/migrations/*.php',
         __DIR__.'/../bootstrap/cache/*',
     ]);
     

   • Add Laravel-focused rules (e.g., enforce use sorting for Laravel classes):

     $ecsConfig->ruleWithConfiguration(
         \Symplify\EasyCodingStandard\ValueObject\Option\SetList::FIXER,
         \NunoMaduro\Collision\Rule\OrderedUseStatementRule::class,
         [
             'order' => \NunoMaduro\Collision\ValueObject\OrderedUseStatement::LARAVEL_ORDER,
         ]
     );
     

2. Team Onboarding

   • Document the standard in your CONTRIBUTING.md:

     ## Coding Standards
     Run `vendor/bin/ecs check app/` to validate your changes.
     

   • Use CI/CD (e.g., GitHub Actions):

     # .github/workflows/ecs.yml
     name: PHP Coding Standard
     on: [push, pull_request]
     jobs:
       ecs:
         runs-on: ubuntu-latest
         steps:
           - uses: actions/checkout@v4
           - run: composer install
           - run: vendor/bin/ecs check app/ --config vendor/whatwedo/php-coding-standard/config/whatwedo-symfony.php
     

3. Incremental Adoption

   • Start with non-breaking checks (e.g., ecs check --no-cache).
   • Gradually introduce fixes via ecs fix for low-impact rules (e.g., spacing, line breaks).

Gotchas and Tips

Pitfalls

1. False Positives in Laravel

   • Issue: Rules like UnusedPrivateMethod may flag Laravel-generated methods (e.g., handle() in controllers).
   • Fix: Skip entire classes or methods:

     $ecsConfig->skip([
         \SlevomatCodingStandard\Sniffs\Classes\UnusedPrivateMethodSniff::class => [
             __DIR__.'/../app/Http/Controllers/*',
         ],
     ]);
     

2. Performance with Large Codebases

   • Issue: Running ecs check on app/ can be slow for monorepos or large apps.
   • Fix:
     • Parallelize checks with --parallel (requires ecs ≥ v9.0):

       vendor/bin/ecs check app/ --parallel --config=...
       

     • Exclude heavy directories (e.g., tests):

       $ecsConfig->paths([__DIR__.'/../app', '!app/Tests']);
       

3. Configuration Overrides

   • Issue: Merging whatwedo-symfony.php with custom rules may cause conflicts.
   • Fix: Use ECSConfig::import() to merge presets:

     $ecsConfig->import(__DIR__.'/vendor/whatwedo/php-coding-standard/config/whatwedo-symfony.php');
     $ecsConfig->ruleWithConfiguration(\Symplify\EasyCodingStandard\ValueObject\Option\SetList::FIXER, ...);
     

Debugging

• Verbose Output: Use --verbose to diagnose skipped files/rules:

  vendor/bin/ecs check app/ --verbose
  

• Dry Run: Test changes without modifying files:

  vendor/bin/ecs check app/ --dry-run
  

Extension Points

1. Custom Rules Add project-specific rules (e.g., enforce Illuminate\Support\Facades\ aliases):

   $ecsConfig->ruleWithConfiguration(
       \Symplify\EasyCodingStandard\ValueObject\Option\SetList::FIXER,
       \WhatWedo\CustomRule\LaravelFacadeRule::class,
       ['alias' => 'Auth::user()']
   );
   

2. Dynamic Paths Use Laravel’s service container to define paths dynamically:

   $ecsConfig->paths(
       array_merge(
           [__DIR__.'/../app'],
           app()->make(\Illuminate\Filesystem\Filesystem::class)
               ->glob(__DIR__.'/../modules/*/src')
       )
   );
   

3. CI-Specific Configs Override rules for CI (e.g., stricter checks):

   if (getenv('CI')) {
       $ecsConfig->ruleWithConfiguration(\Symplify\EasyCodingStandard\ValueObject\Option\SetList::PSR_12, ...);
   }