Cs Fixer Config Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require --dev wayofdev/cs-fixer-config
   

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

   <?php
   declare(strict_types=1);
   
   use WayOfDev\PhpCsFixer\Config\ConfigBuilder;
   use WayOfDev\PhpCsFixer\Config\RuleSets\DefaultSet;
   
   require_once 'vendor/autoload.php';
   
   return ConfigBuilder::createFromRuleSet(new DefaultSet())
       ->inDir(__DIR__ . '/src')
       ->inDir(__DIR__ . '/tests')
       ->getConfig();
   

3. First Use Case: Run a dry-run to preview changes:

   composer cs:diff
   

Where to Look First

• RuleSets: Explore WayOfDev\PhpCsFixer\Config\RuleSets\ for predefined configurations (DefaultSet, ExtendedPERSet).
• ConfigBuilder: Review ConfigBuilder methods for customization (e.g., inDir(), addFiles()).
• Composer Scripts: Check the scripts section in composer.json for predefined commands.

Implementation Patterns

Core Workflows

1. Project Setup:

   • Use DefaultSet for Symfony-like standards or ExtendedPERSet for PER-CS2.0 compliance.
   • Scope rules to specific directories:

     ->inDir(__DIR__ . '/src')
       ->inDir(__DIR__ . '/tests')
     

2. File Inclusion:

   • Explicitly include files (e.g., config files):

     ->addFiles([__FILE__])
     

3. Cache Optimization:

   • Enable caching for faster subsequent runs:

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

4. CI/CD Integration:

   • Use composer cs:fix in GitHub Actions to auto-fix and commit changes (see example workflow).

Integration Tips

• Makefile: Leverage pre-built Makefile targets for lint-php and lint-diff (see template).
• Git Hooks: Add a pre-commit hook to run composer cs:diff and block non-compliant code:

  composer cs:diff || exit 1
  

• Custom Rules: Extend DefaultSet by overriding rules:

  use WayOfDev\PhpCsFixer\Config\RuleSets\DefaultSet as BaseSet;
  
  class CustomSet extends BaseSet {
      protected function getRules(): array {
          return array_merge(parent::getRules(), [
              '@PSR12' => true,
              'no_unused_imports' => true,
          ]);
      }
  }
  

Gotchas and Tips

Pitfalls

1. Cache Directory:

   • Forgetting to add .build/ to .gitignore may bloat your repo with cached files.
   • Fix: Explicitly ignore .build/php-cs-fixer/ in .gitignore.

2. Rule Conflicts:

   • Mixing DefaultSet and ExtendedPERSet may cause unexpected rule overlaps.
   • Fix: Stick to one rule set per project or merge them intentionally.

3. Dry-Run Misuse:

   • composer cs:diff shows changes but doesn’t apply them. Always review the diff before committing auto-fixes.

4. PHP Version Mismatch:

   • The package requires PHP 8.1+. Older versions may fail silently.
   • Fix: Update your PHP environment or pin a compatible version in composer.json.

Debugging Tips

• Verbose Output: Use -v flag for detailed logs:

  composer cs:fix -v
  

• Rule Validation: Validate rules with the PHP-CS-Fixer Configurator to ensure compatibility.
• Cache Issues: Clear the cache manually if rules aren’t applying:

  rm -rf .build/php-cs-fixer/cache
  

Extension Points

1. Custom RuleSets: Extend WayOfDev\PhpCsFixer\Config\RuleSets\AbstractRuleSet to create reusable configurations:

   class MyRuleSet extends AbstractRuleSet {
       protected function getRules(): array {
           return [
               'array_syntax' => ['syntax' => 'short'],
               'concat_space' => ['spacing' => 'one'],
           ];
       }
   }
   

2. Dynamic Configs: Use ConfigBuilder methods like setFinder() to dynamically include/exclude files based on patterns:

   ->setFinder(
       (new \PhpCsFixer\Finder())
           ->in(__DIR__)
           ->exclude(['vendor', 'node_modules'])
   )
   

3. Environment-Specific Rules: Override rules in CI vs. local development:

   if (getenv('CI')) {
       $config->setRiskyAllowed(true); // Enable riskier fixes in CI
   }
   

Pro Tips

• Atomic Commits: Run composer cs:fix locally before committing to avoid large, noisy PRs.
• Pre-Merge Checks: Use GitHub Actions to enforce CS fixes on pull_request events (see workflow template).
• Team Alignment: Document your chosen rule set (e.g., DefaultSet) in CONTRIBUTING.md to align contributors.