Php Cs Fixer Laravel Package

Getting Started

Minimal Setup

1. Installation:

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

   For Laravel projects, ensure it’s in devDependencies to avoid production bloat.

2. Initialize Config:

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

   This generates a .php-cs-fixer.dist.php file with a default Symfony rule set—ideal for Laravel.

3. First Run:

   ./vendor/bin/php-cs-fixer fix src tests --dry-run
   

   Use --dry-run to preview changes before committing.

Key Commands

Implementation Patterns

Workflow Integration

1. Pre-Commit Hooks: Use php-cs-fixer in a Git pre-commit hook to enforce consistency:

   # .git/hooks/pre-commit
   #!/bin/sh
   ./vendor/bin/php-cs-fixer fix --dry-run --diff || exit 1
   

   Tip: Combine with phpstan or psalm for a full static analysis pipeline.

2. CI/CD 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
   

   Use --allow-risky for experimental rules (e.g., @autoPHPMigration).

3. Editor Integration:

   • PhpStorm: Enable built-in PHP-CS-Fixer via Settings > Tools > PHP > PHP-CS-Fixer.
   • VS Code: Use the PHP-CS-Fixer extension for on-save fixes.

Laravel-Specific Patterns

1. Custom Rule Sets: Extend the default Symfony ruleset for Laravel conventions:

   // .php-cs-fixer.dist.php
   return (new PhpCsFixerConfig())
       ->setRules([
           '@Symfony' => true,
           'no_unused_imports' => true, // Laravel-specific
           'ordered_imports' => ['sort_algorithm' => 'alpha'],
           'native_function_casing' => true,
           'php_unit_method_casing' => ['case' => 'snake_case'], // Laravel tests
       ]);
   

2. Partial Fixes: Target specific directories (e.g., avoid fixing vendor files):

   ./vendor/bin/php-cs-fixer fix app/Http app/Console --path-mode=intersection
   

3. Risky Rules: Use @autoPHPMigration to modernize PHP versions (e.g., PHP 8.1+):

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

Gotchas and Tips

Common Pitfalls

1. Performance:

   • Exclude large files (e.g., generated code) to speed up runs:

     ->setExclude(['storage/*', 'bootstrap/cache/*'])
     

   • Cache results with --cache-file=.php-cs-fixer.cache.

2. Rule Conflicts:

   • Some rules (e.g., array_syntax) may break functionality. Test risky rules in a branch first.
   • Use --dry-run to preview changes before applying.

3. PHP Version Mismatches:

   • If your project uses PHP 8.2 but CS Fixer defaults to PHP 7.4, add:

     ./vendor/bin/php-cs-fixer fix --php-version=8.2
     

   • For unsupported versions, use --allow-unsupported-php-version=yes (at your own risk).

4. False Positives:

   • Rules like no_unused_imports may flag Laravel’s dynamic imports (e.g., use Illuminate\Support\Facades\Route;). Exclude them:

     ->setRules(['no_unused_imports' => ['ignore_relative_imports' => false, 'ignore_missing' => true]])
     

Debugging Tips

1. Verbose Output: Use -v to debug rule application:

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

2. Rule Descriptions: List rules with descriptions:

   ./vendor/bin/php-cs-fixer describe-rules
   

3. Custom Config Validation: Validate your config file:

   ./vendor/bin/php-cs-fixer validate-ruleset
   

Extension Points

1. Custom Rules: Create a custom rule for Laravel-specific patterns (e.g., Blade directives):

   // CustomRule.php
   use PhpCsFixer\Fixer\FixerInterface;
   use PhpCsFixer\Tokenizer\Tokens;
   
   class LaravelBladeSpacingFixer implements FixerInterface { ... }
   

   Register it in .php-cs-fixer.dist.php:

   ->registerCustomFixers([__DIR__.'/CustomRule.php'])
   

2. Rule Sets: Combine multiple rule sets:

   ->setRules([
       '@Symfony' => true,
       '@PSR12' => true,
       'concat_space' => ['spacing' => 'one'],
   ])
   

3. Parallel Processing: Speed up large codebases with --parallel:

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

Laravel-Specific Quirks

1. Facade Imports: Avoid fixing use Illuminate\Support\Facades\Log; to use Log; if your team prefers facades for clarity.

2. Dynamic Properties: Rules like no_unused_private_members may flag Laravel’s dynamic properties (e.g., $app). Exclude them:

   ->setRules(['no_unused_private_members' => false])
   

3. Artisan Commands: Test CS Fixer on generated commands (e.g., php artisan make:command) to avoid breaking changes.