Coding Standard Laravel Package

Getting Started

Minimal Setup

1. Install the package in your Laravel project:

   composer require --dev innmind/coding-standard
   

2. Create .php_cs.dist at your project root with the basic config:

   <?php
   return \Innmind\CodingStandard\CodingStandard::config(['app', 'routes', 'src', 'tests']);
   

   (Adjust paths to match your Laravel structure.)

3. Run the fixer once to auto-correct:

   vendor/bin/php-cs-fixer fix
   

First Use Case

• Pre-commit hook: Add to .git/hooks/pre-commit:

  #!/bin/sh
  vendor/bin/php-cs-fixer fix --dry-run --diff
  

  (Fails if changes are needed, enforcing consistency before commits.)

Implementation Patterns

Workflows

1. Team Onboarding

   • Share .php_cs.dist via Git (or template it in vendor/).
   • New devs run composer install + php-cs-fixer fix to align their IDE.

2. CI Integration

   # .github/workflows/php-cs.yml
   jobs:
     coding-standard:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
         - run: composer install
         - run: vendor/bin/php-cs-fixer fix --dry-run --diff --allow-risky=yes
   

   (Fail builds if fixes are needed, but allow risky changes in CI.)

3. Partial Fixes

   • Target specific files/directories:

     vendor/bin/php-cs-fixer fix app/Http/Controllers --rules=@Innmind
     

Laravel-Specific Tips

• Exclude Vendor/Generated Files:

  CodingStandard::config([
      'app', 'routes', 'src',
      'tests',
  ], [
      'vendor/*',
      'bootstrap/cache/*',
      'storage/framework/*',
  ]);
  

• IDE Integration:
  • Use php-cs-fixer as a PHPStan/PSR-12 rule provider in PHPStorm:

    <!-- php-cs-fixer.xml.dist -->
    <config cacheFile=".php_cs.cache">
      <rule ref="Innmind"/>
    </config>
    

Gotchas and Tips

Pitfalls

1. Rule Conflicts

   • Innmind’s rules may override Laravel’s default PSR-12 (e.g., strict return spacing).
   • Fix: Merge with existing .php_cs.dist or use --rules to override:

     vendor/bin/php-cs-fixer fix --rules=@PSR12,@Innmind
     

2. Performance

   • Large codebases (e.g., Laravel + plugins) may slow down php-cs-fixer.
   • Tip: Cache results with --cache-file=.php_cs.cache and exclude heavy directories.

3. False Positives

   • Innmind’s rules might flag Laravel-specific patterns (e.g., Route::group nesting).
   • Workaround: Add exceptions to .php_cs.dist:

     CodingStandard::config([], [
         'rules' => [
             '@Innmind' => true,
             'no_unused_imports' => false, // Disable for Laravel's Facades
         ],
     ]);
     

Debugging

• Dry Run: Always use --dry-run first to preview changes:

  vendor/bin/php-cs-fixer fix --dry-run --diff
  

• Verbose Mode: Debug rule application:

  vendor/bin/php-cs-fixer fix -v
  

Extension Points

1. Custom Rules
   • Extend Innmind’s rules by creating a child config:

     // .php_cs.dist
     return CodingStandard::config(['app'], [
         'rules' => [
             'Innmind\\Rules\\ClassAlignment' => true,
             'custom_rule' => MyCustomRule::class,
         ],
     ]);
     

2. Parallel Processing
   • Speed up fixes with --parallel (requires PHP 8.1+):

     vendor/bin/php-cs-fixer fix --parallel=4
     

Laravel Quirks

• Facade Imports: Innmind’s rules may flag unused use statements for Facades. Solution: Whitelist Laravel’s Facades in .php_cs.dist:

  CodingStandard::config([], [
      'exclude' => [
          'rules' => ['no_unused_imports' => ['App\\Providers\\RouteServiceProvider' => true]],
      ],
  ]);