Php Cs Fixer Laravel Package

Getting Started

Minimal Steps

1. Installation Add to composer.json under require-dev:

   "friendsofphp/php-cs-fixer": "^3.95"
   

   Run:

   composer require --dev friendsofphp/php-cs-fixer
   

2. Initialize Config Generate a default config file:

   ./vendor/bin/php-cs-fixer init
   

   This creates .php-cs-fixer.dist.php with a basic Symfony rule set.

3. First Run Fix files interactively or dry-run:

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

   Apply fixes:

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

Where to Look First

• Rule Sets: Predefined sets like @Symfony, @PSR12, or @PhpCsFixer in docs.
• Config File: .php-cs-fixer.dist.php for custom rules (e.g., return_type_declaration).
• Editor Integration: Use PhpStorm’s built-in CS Fixer or VS Code plugins for on-save fixes.

First Use Case

Run CS Fixer on a Laravel project’s app/ directory:

./vendor/bin/php-cs-fixer fix app/ --rules=@PSR12 --allow-risky=yes

Implementation Patterns

Workflows

1. Pre-Commit Hook Integrate with Laravel’s Git hooks (e.g., pre-commit) to auto-fix:

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

   Use tools like php-cs-fixer Git hook.

2. CI Pipeline Add to Laravel’s CI (e.g., GitHub Actions):

   - name: Run PHP-CS-Fixer
     run: ./vendor/bin/php-cs-fixer fix --diff --allow-risky=yes --stop-on-violation
   

3. Custom Rule Sets Extend .php-cs-fixer.dist.php for Laravel-specific rules:

   return PhpCsFixer\Config::create()
       ->setRules([
           '@PSR12' => true,
           'no_unused_imports' => true,
           'ordered_imports' => ['sort_algorithm' => 'alpha'],
           'native_function_invocation' => ['include' => ['@compiler_optimized']],
           'php_unit_test_class_requires_covers' => false, // Laravel-specific
       ]);
   

4. Partial Fixes Target specific files/directories:

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

Integration Tips

• Laravel Mix/Webpack: Add CS Fixer to postcss or webpack.mix.js via custom scripts.
• IDE Sync: Use PhpStorm’s “Reformat Code” with CS Fixer as the formatter.
• Team Onboarding: Include CS Fixer in README.md with:

  composer require --dev friendsofphp/php-cs-fixer
  ./vendor/bin/php-cs-fixer fix
  

Gotchas and Tips

Pitfalls

1. Risky Rules Avoid @auto:risky or @autoPHPMigration:risky in production:

   ./vendor/bin/php-cs-fixer fix --allow-risky=no
   

   Example: return_type_declaration may break legacy PHP 7.0 code.

2. False Positives Disable rules for specific files:

   return PhpCsFixer\Config::create()
       ->setRules([
           'no_unused_imports' => true,
       ])
       ->setPath('.php-cs-fixer.dist.php')
       ->setExclude(['vendor/', 'storage/framework/views/*.php']);
   

3. Performance Exclude large files (e.g., generated Blade views):

   ./vendor/bin/php-cs-fixer fix --exclude='storage/framework/views'
   

4. PHP Version Mismatches Use --allow-unsupported-php-version=yes for PHP 8.5+ (experimental):

   ./vendor/bin/php-cs-fixer fix --allow-unsupported-php-version=yes
   

Debugging

• Dry Run: Always use --diff first:

  ./vendor/bin/php-cs-fixer fix --diff
  

• Verbose Mode: Debug rule application:

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

• Cache Issues: Clear cache if rules fail silently:

  ./vendor/bin/php-cs-fixer fix --cache-file=~/.php-cs-fixer.cache
  

Tips

1. Laravel-Specific Rules Add these to .php-cs-fixer.dist.php:

   'php_unit_test_class_requires_covers' => false, // Laravel tests
   'native_function_type_declaration' => ['skip_closure Implementations' => true],
   

2. Editor Shortcuts

   • PhpStorm: Ctrl+Alt+Shift+F → Configure “Code Reformatter” to use CS Fixer.
   • VS Code: Use the PHP CS Fixer extension.

3. Custom Rules Extend CS Fixer for Laravel-specific fixes (e.g., laravel_eloquent_method_casing):

   $finder = PhpCsFixer\Finder::create()
       ->in(__DIR__.'/app/Models')
       ->name('*.php');
   $config = new PhpCsFixer\Config();
   $config->registerCustomFixers([
       new Custom\LaravelEloquentFixer(),
   ]);
   

4. Configuration Inheritance Use extends to inherit from another config:

   return PhpCsFixer\Config::create()
       ->extends(__DIR__.'/vendor/laravel/framework/.php-cs-fixer.dist.php')
       ->setRules(['no_unused_imports' => true]);
   

5. Git Attributes Auto-fix on git add via .gitattributes:

   *.php filter=php-cs-fixer
   

   Requires git-filter-repo.

6. CI Feedback Fail CI on violations (GitHub Actions example):

   - name: PHP-CS-Fixer
     run: |
       if ! ./vendor/bin/php-cs-fixer fix --dry-run --diff --stop-on-violation; then
         echo "::error::PHP-CS-Fixer found violations"
         exit 1
       fi