Php Cs Fixer Config Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require --dev ergebnis/php-cs-fixer-config:^6.62.3
   

   Add to composer.json under require-dev if not using --dev.

2. Create Config File: Place .php-cs-fixer.php in your project root with the updated minimal setup:

   <?php
   declare(strict_types=1);
   
   use Ergebnis\PhpCsFixer\Config;
   use PhpCsFixer\Finder;
   
   $config = Config\Factory::fromRuleSet(Config\RuleSet\Php83::create());
   $config->setFinder(Finder::create()->in(__DIR__));
   $config->setCacheFile(__DIR__ . '/.build/php-cs-fixer/.php-cs-fixer.cache');
   
   return $config;
   

3. First Use Case: Run PHP-CS-Fixer directly:

   vendor/bin/php-cs-fixer fix
   

   Or integrate into CI (see GitHub Actions below).

Implementation Patterns

1. Rule Set Selection

• Version Alignment: Choose a rule set matching your project’s PHP version (e.g., Php83 for PHP 8.3).

  $ruleSet = Config\RuleSet\Php83::create();
  

• Customization: Extend base rule sets with overrides (see Overriding Rules).

2. Finder Configuration

• Target Directories:

  $finder = Finder::create()
      ->in(['src', 'tests'])
      ->exclude(['vendor', 'node_modules']);
  

• File Patterns:

  ->name('*.php')
  ->notName('*.blade.php') // Exclude Blade templates
  

3. Integration Workflows

Composer Scripts

Add to composer.json:

"scripts": {
  "cs-fix": [
    "mkdir -p .build/php-cs-fixer",
    "@php-cs-fixer"
  ],
  "php-cs-fixer": "php-cs-fixer fix --config=.php-cs-fixer.php --diff --verbose"
}

Run:

composer cs-fix

Git Hooks

Add a pre-commit hook in .git/hooks/pre-commit:

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

CI/CD

Use in GitHub Actions (updated dependencies in 6.62.3):

- uses: actions/checkout@v7
- uses: zizmorcore/zizmor-action@v0.5.7
  with:
    php-cs-fixer: true

4. Header Management

Enable file headers globally:

$ruleSet = Config\RuleSet\Php83::create()->withHeader($yourHeaderString);

5. Custom Fixers

Register third-party fixers (e.g., from erickskrauch/php-cs-fixer-custom-fixers):

$ruleSet = Config\RuleSet\Php83::create()
    ->withCustomFixers(Config\Fixers::fromFixers(
        new \ErickSkrauch\PhpCsFixerCustomFixers\Fixer\FooFixer()
    ))
    ->withRules(Config\Rules::fromArray([
        'ErickSkrauch\Foo' => true,
    ]));

Gotchas and Tips

Pitfalls

1. Cache Directory:

   • Forgetting to add .build/php-cs-fixer/ to .gitignore can bloat your repo.
   • Fix: Use mkdir -p .build/php-cs-fixer in scripts to auto-create it.

2. Rule Conflicts:

   • Overriding rules may break compatibility with the target PHP version.
   • Fix: Check the changelog for version-specific fixes (e.g., get_called_class in PHP 8.3).

3. Custom Fixer Dependencies:

   • Missing dependencies for custom fixers (e.g., erickskrauch/php-cs-fixer-custom-fixers) will cause errors.
   • Fix: Install them explicitly:

     composer require --dev erickskrauch/php-cs-fixer-custom-fixers
     

4. Performance:

   • Large codebases may slow down PHP-CS-Fixer. Use --parallel for speed:

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

Debugging Tips

• Dry Run: Always test changes first:

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

• Verbose Output: Add --verbose to diagnose issues.
• Rule Validation: Use php-cs-fixer validate to check config syntax.

Extension Points

1. Dynamic Rule Sets: Load rule sets dynamically based on environment (e.g., Php74 for legacy branches):

   $ruleSet = Config\RuleSet\Php74::create();
   if (app()->environment('production')) {
       $ruleSet = Config\RuleSet\Php83::create();
   }
   

2. Laravel-Specific:

   • Publishing Config: Publish the config file in a Laravel package:

     // In your PackageServiceProvider
     $this->publishes([
         __DIR__.'/config/php-cs-fixer.php' => config_path('php-cs-fixer.php'),
     ]);
     

   • Artisan Command: Create a custom command:

     // app/Console/Commands/FixCs.php
     use Symfony\Component\Process\Process;
     
     class FixCs extends Command {
         protected $signature = 'cs:fix';
         public function handle() {
             $process = new Process(['vendor/bin/php-cs-fixer', 'fix']);
             $process->run();
             $this->output->write($process->getOutput());
         }
     }
     

3. Rule Set Inheritance: Extend existing rule sets in your config:

   class CustomRuleSet extends Config\RuleSet\Php83 {
       public static function create(): self {
           $ruleSet = parent::create();
           return $ruleSet->withRules(Config\Rules::fromArray([
               'array_syntax' => ['syntax' => 'short'],
           ]));
       }
   }
   

Configuration Quirks

• Header Formatting: The HeaderCommentFixer respects YAML-style headers but may strip existing comments. Use --allow-risky=yes cautiously.
• Custom Fixer Order: Register fixers before enabling their rules to avoid "unknown fixer" errors.
• Finder Exclusions: Use ->notPath() for complex exclusions (e.g., ->notPath(['*/Resources/*'])).

Pro Tips

1. Team Alignment:

   • Pin the package version in composer.json to avoid unexpected rule changes:

     "ergebnis/php-cs-fixer-config": "^6.62.3"
     

2. Partial Fixes: Use --path-mode=intersection to fix only files matching both your finder and PHP-CS-Fixer’s rules.

3. IDE Integration: Configure PHPStorm to use your .php-cs-fixer.php via: Settings > Editor > Code Style > PHP > PHP-CS-Fixer > Config File.

4. Legacy Support: For PHP 7.4 projects, use Php74 but override risky rules like mb_str_functions:

   ->withRules(Config\Rules::fromArray(['mb_str_functions' => false]))
   

New in 6.62.3

• Dependency Updates:
  • friendsofphp/php-cs-fixer updated to 3.95.11 (includes bug fixes and performance improvements).
  • Updated GitHub Actions dependencies (actions/cache, actions/checkout, zizmorcore/zizmor-action).
  • Updated rector/rector and phpstan/phpstan-phpunit for better static analysis compatibility.
• Configuration Fix:
  • Fixed renew.yaml ignore rule for artipacked (PR #1435). Ensure your .gitignore or CI excludes this file if applicable.