Imbo Coding Standard Laravel Package

Getting Started

Minimal Setup

1. Install Dependencies

   composer require --dev imbo/imbo-coding-standard ^3.0 friendsofphp/php-cs-fixer
   

2. Create Config File Place .php-cs-fixer.dist.php in your project root with:

   <?php declare(strict_types=1);
   require 'vendor/autoload.php';
   
   $finder = new PhpCsFixer\Finder();
   $config = new Imbo\CodingStandard\Config();
   
   return $config
       ->setParallelConfig(PhpCsFixer\Runner\Parallel\ParallelConfigFactory::detect())
       ->setFinder($finder->in(__DIR__)->append([__FILE__]));
   

3. First Use Case Run a dry check to preview violations:

   vendor/bin/php-cs-fixer check --diff
   

Implementation Patterns

Workflow Integration

1. Local Development

   • Add Composer scripts for quick checks:

     {
       "scripts": {
         "cs": "vendor/bin/php-cs-fixer check --diff",
         "cs:fix": "vendor/bin/php-cs-fixer fix --diff"
       }
     }
     

   • Run interactively:

     composer cs:fix
     

2. CI/CD Pipeline

   • Enforce in GitHub Actions (or GitLab CI):

     - name: Check coding standard
       run: vendor/bin/php-cs-fixer check --diff
     

   • Fail builds on violations by omitting --diff.

3. Team Onboarding

   • Document the standard in CONTRIBUTING.md:

     ## Code Style
     Run `composer cs` to validate changes against Imbo’s PHP-CS-Fixer rules.
     

Laravel-Specific Patterns

1. Focused Fixing

   • Target Laravel-specific files (e.g., migrations, service providers):

     $finder->in(__DIR__)
         ->exclude('tests')
         ->append(['config/', 'routes/']);
     

2. Custom Rules

   • Extend the config to add Laravel-specific rules (e.g., no_unused_imports):

     $config->setRules([
         '@Imbo' => true,
         'no_unused_imports' => true,
     ]);
     

3. Pre-Commit Hooks

   • Use php-cs-fixer with tools like Husky:

     composer cs -- --allow-risky=yes
     

Gotchas and Tips

Common Pitfalls

1. Parallel Processing

   • Issue: Slow fixes on large codebases.
   • Fix: Ensure ParallelConfigFactory::detect() is set (default in the config).

2. Rule Conflicts

   • Issue: Imbo’s rules may conflict with other tools (e.g., PSR-12).
   • Fix: Override specific rules in your config:

     $config->setRules([
         '@Imbo' => true,
         'array_syntax' => ['syntax' => 'short'], // Force short array syntax
     ]);
     

3. CI Failures

   • Issue: False positives in CI due to --diff output.
   • Fix: Run without --diff in CI for strict enforcement:

     run: vendor/bin/php-cs-fixer check
     

Debugging Tips

1. Verbose Output

   • Debug rule application:

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

2. Rule Whitelisting

   • Temporarily disable rules for legacy code:

     $finder->notPath('legacy/');
     

3. Custom Rule Sets

   • Inspect Imbo’s rules via:

     vendor/bin/php-cs-fixer fix --rules=@Imbo --dry-run --verbose
     

Extension Points

1. Add Custom Rules

   • Extend the config to include additional rulesets (e.g., @Symfony):

     $config->setRules([
         '@Imbo' => true,
         '@Symfony' => true,
     ]);
     

2. Cache Configuration

   • Speed up repeated runs by caching the config:

     $config->setCacheFile(__DIR__ . '/.php-cs-fixer.cache');
     

3. Path Exclusions

   • Exclude vendor or generated files:

     $finder->exclude([
         'vendor/',
         'bootstrap/cache/',
     ]);