Code Style Laravel Package

Getting Started

Minimal Setup

1. Install Dependencies

   composer require --dev friendsofphp/php-cs-fixer eloquent/code-style
   

   Ensure php-cs-fixer is installed as a dev dependency.

2. Generate Config File Create .php-cs-fixer.php in your project root:

   <?php return Eloquent\CodeStyle\Config::create(__DIR__);
   

   This auto-configures the tool with Eloquent’s preferred PSR-12 + custom rules.

3. First Run Fix files in your project:

   vendor/bin/php-cs-fixer fix
   

   Target specific files/directories:

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

4. Check Without Fixing Dry-run to preview changes:

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

Implementation Patterns

Workflow Integration

1. Pre-Commit Hook Add to .git/hooks/pre-commit (or use tools like husky):

   #!/bin/sh
   vendor/bin/php-cs-fixer fix --diff --dry-run --allow-risky=yes
   

   • --diff: Only check staged files.
   • --allow-risky: Skip risky fixes (e.g., line endings).

2. CI Pipeline Enforce style in CI (e.g., GitHub Actions):

   - name: PHP-CS-Fixer
     run: vendor/bin/php-cs-fixer fix --level=all --allow-risky=yes --diff
   

3. Customizing Rules Extend the config to override defaults:

   $config = Eloquent\CodeStyle\Config::create(__DIR__);
   $config->getRules()->remove('no_unused_imports'); // Disable a rule
   $config->getRules()->set('array_syntax', 'short'); // Force short array syntax
   return $config;
   

4. Partial Fixes Fix only specific rules:

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

Common Use Cases

• Onboarding: Run fix on new dev machines to align with team standards.
• Pull Requests: Use --diff to highlight style changes in PRs.
• Legacy Code: Exclude old directories (e.g., vendor/, artifacts/) via $config->getFinder()->exclude().

Gotchas and Tips

Pitfalls

1. Archived Package

   • No active maintenance; rules may diverge from modern PSR standards.
   • Mitigation: Audit rules against PSR-12 and override as needed.

2. Risky Fixes

   • --allow-risky=yes is required for some rules (e.g., line endings).
   • Tip: Test risky fixes locally first with --dry-run.

3. Finder Quirks

   • Excluded paths must match your project structure exactly (e.g., test/fixture vs. tests/fixtures).
   • Debug: Run vendor/bin/php-cs-fixer fix --verbose to see processed files.

4. Rule Conflicts

   • Eloquent’s config may conflict with other tools (e.g., phpstan).
   • Solution: Merge configs or use --rules to isolate rules.

Debugging

• Verbose Mode

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

  Reveals skipped files and applied rules.

• Rule-Specific Fixes Target a single rule to isolate issues:

  vendor/bin/php-cs-fixer fix --rules=@Eloquent --rules=braces
  

Extension Points

1. Custom Rules Combine with other rule sets (e.g., Symfony):

   $config->getRules()->import('@Symfony');
   

2. Path Overrides Use paths() to limit scope:

   $config->getFinder()->paths(['src', 'app']);
   

3. Cache Improve performance with caching:

   vendor/bin/php-cs-fixer fix --cache=no  # Disable cache for debugging