Easy Coding Standard Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require --dev symplify/easy-coding-standard
   

   Add to composer.json under require-dev:

   "extra": {
       "laravel": {
           "start": "php artisan serve",
           "ecs": {
               "config": "ecs.php"
           }
       }
   }
   

2. Initialize Config:

   vendor/bin/ecs init
   

   This generates ecs.php with default PSR-12 rules.

3. First Run:

   vendor/bin/ecs check src/
   

   Fix issues automatically:

   vendor/bin/ecs check src/ --fix
   

Key First Use Case

Integrate into CI/CD (e.g., GitHub Actions):

- name: Run ECS
  run: vendor/bin/ecs check src/ --no-interaction --diff

Add to composer.json scripts:

"scripts": {
    "cs-check": "ecs check src/ --no-interaction --diff",
    "cs-fix": "ecs check src/ --fix"
}

Implementation Patterns

Core Workflows

1. Project-Wide Enforcement:

   // ecs.php
   return static function (ECSConfig $ecsConfig): void {
       $ecsConfig->paths([
           __DIR__.'/src',
           __DIR__.'/app',
           __DIR__.'/routes',
       ]);
       $ecsConfig->sets([
           SetList::PSR_12,
           SetList::SYMFONY,
           SetList::LARAVEL, // Laravel-specific rules
       ]);
   };
   

2. Per-Module Rules (for large apps):

   $ecsConfig->paths([__DIR__.'/modules/auth']);
   $ecsConfig->rules([
       LineEnding::class => ['line_ending' => "\n"],
       NoUnusedImports::class,
   ]);
   

3. Custom Rulesets:

   $ecsConfig->ruleWithConfiguration(
       ClassNameLengthRule::class,
       ['max' => 30] // Custom threshold
   );
   

Integration Tips

• Laravel-Specific Rules: Use SetList::LARAVEL for Eloquent/Blade conventions. Extend with custom rules:

  $ecsConfig->rule(NoUnusedUsesRule::class);
  $ecsConfig->rule(NoUnusedImportsRule::class);
  

• CI Optimization: Cache results with --cache flag or use --parallel for multi-core speedups:

  vendor/bin/ecs check --parallel --cache
  

• IDE Integration: Add to .editorconfig:

  [*.php]
  ecs_ignore = false
  

• Git Hooks: Use pre-commit hook to auto-fix:

  vendor/bin/ecs check --fix --skip=tests
  

Gotchas and Tips

Pitfalls

1. Parallel Mode Conflicts:

   • Enable --parallel cautiously in CI; some rules (e.g., NoUnusedImports) may misbehave.
   • Debug with --debug to log parallelization issues.

2. Laravel-Specific Quirks:

   • Blade Templates: Exclude resources/views by default:

     $ecsConfig->exclude([__DIR__.'/resources/views']);
     

   • Artisan Commands: Add to paths:

     $ecsConfig->paths([__DIR__.'/app/Console/Commands']);
     

3. Rule Overrides:

   • Avoid overriding PSR_12 rules unless necessary; use skip for exceptions:

     $ecsConfig->skip([
         __DIR__.'/app/Exceptions/Handler.php',
     ]);
     

4. PHP Version Mismatches:

   • ECS 13+ requires PHP 8.1+. For Laravel 7 (PHP 7.4), pin to ~12.6:

     composer require symplify/easy-coding-standard:^12.6
     

Debugging

• Verbose Output:

  vendor/bin/ecs check --verbose
  

• Dry Run:

  vendor/bin/ecs check --dry-run
  

• Rule-Specific Debugging:

  vendor/bin/ecs check --rules=NoUnusedImports --debug
  

Extension Points

1. Custom Rules: Create a rule class (e.g., app/Rules/CustomLaravelRule.php) and register it:

   $ecsConfig->rule(CustomLaravelRule::class);
   

2. Dynamic Configs: Load configs from environment variables:

   $ecsConfig->paths([env('ECS_PATHS', __DIR__.'/src')]);
   

3. Output Formats: Generate CI-friendly reports:

   vendor/bin/ecs check --format=checkstyle > ecs-report.xml
   

Pro Tips

• Incremental Adoption: Start with --fix and gradually enable stricter rules via sets().
• Team Alignment: Use ecs --version to ensure all devs use the same ECS/PHP-CS-Fixer versions.
• Performance: Exclude vendor/ and node_modules/ from paths to speed up runs.
• Laravel Artisan Integration: Add a custom command:

  // app/Console/Commands/ECSCommand.php
  public function handle() {
      $exitCode = (new ECS())->run();
      exit($exitCode);
  }