Coding Standard Laravel Package

Getting Started

Minimal Setup

1. Installation:

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

   • Ensure symplify/easy-coding-standard (ECS) is installed as the core runner.

2. Configuration: Add the Symplify set to your ecs.php:

   use Symplify\EasyCodingStandard\Config\ECSConfig;
   
   return ECSConfig::configure()
       ->withPreparedSets(symplify: true);
   

3. First Run:

   vendor/bin/ecs check  # Dry-run (no changes)
   vendor/bin/ecs fix     # Auto-fix violations
   

First Use Case

• Onboarding: Run ecs fix during a new developer’s setup to standardize their codebase contributions.
• PR Reviews: Use ecs check in CI to enforce consistency before merging.

Implementation Patterns

Workflows

1. Team Enforcement:

   • Integrate with Git hooks (e.g., pre-commit) to auto-fix issues:

     composer require --dev laravel-pint/laravel-pint  # Optional: Combine with Pint
     

   • Example .git/hooks/pre-commit:

     #!/bin/sh
     vendor/bin/ecs check --diff
     

2. Customization:

   • Extend the config to exclude specific files/directories:

     ->withPaths(['src/', 'tests/'])
     ->withSkip(['src/legacy/*.php']);
     

   • Override rules (e.g., adjust LineLengthFixer):

     ->withRule(Symplify\CodingStandard\Fixer\LineLength\LineLengthFixer::class)
         ->lineLength(120)
         ->skip(['*/migrations/*.php']);
     

3. CI/CD:

   • Fail builds on violations:

     # .github/workflows/ecs.yml
     jobs:
       ecs:
         runs-on: ubuntu-latest
         steps:
           - run: vendor/bin/ecs check
     

Integration Tips

• With PHPStan/Psalm: Use the @phpstan-/@psalm- prefixed docblock rules (e.g., AddMissingParamNameFixer).
• With Laravel: Exclude vendor/, bootstrap/, and config/ from checks:

  ->withPaths(['app/', 'routes/', 'database/']);
  

• Parallel Execution: Speed up runs with --parallel:

  vendor/bin/ecs fix --parallel
  

Gotchas and Tips

Pitfalls

1. False Positives:

   • DocBlock Rules: The RemovePropertyVariableNameDescriptionFixer may misfire on complex PHPDoc blocks. Test edge cases like:

     /** @var string $name|string[] */
     

   • Workaround: Exclude specific files or use --skip:

     vendor/bin/ecs fix --skip=RemovePropertyVariableNameDescriptionFixer
     

2. Performance:

   • Large codebases (>10K files) may slow down ECS. Use --parallel or split paths:

     vendor/bin/ecs check app/ tests/
     

3. Overzealous Fixes:

   • LineLengthFixer: May break long SQL queries or regex. Skip migrations:

     ->withRule(LineLengthFixer::class)->skip(['*/migrations/*.php']);
     

Debugging

• Dry-Run Inspection: Use --diff to preview changes:

  vendor/bin/ecs check --diff
  

• Verbose Output: Debug rule application:

  vendor/bin/ecs fix -vvv
  

Extension Points

1. Custom Rules: Extend Symplify\EasyCodingStandard\ValueObject\Option to add new fixers:

   // CustomFixer.php
   use Symplify\EasyCodingStandard\Fixer\FixerInterface;
   
   class CustomFixer implements FixerInterface { ... }
   
   // ecs.php
   ->withRule(CustomFixer::class);
   

2. Rule Sets: Combine with other sets (e.g., PSR12):

   ->withPreparedSets(
       symplify: true,
       psr12: true
   );
   

3. Conditional Rules: Use ECSConfig::configure() to conditionally enable rules:

   ->withRule(StandaloneLineConstructorParamFixer::class)
       ->if($this->isPHP80());
   

Pro Tips

• IDE Integration: Configure PHPStorm to use ECS for inspections (Settings > Languages & Frameworks > PHP > Quality Tools).
• Legacy Code: Gradually enforce rules by excluding paths and re-enabling over time.
• Documentation: Add a CONTRIBUTING.md snippet:

  ## Code Standards
  Run `composer ecs` to auto-fix issues before committing.