Php Cs Fixer Laravel Package

Getting Started

Minimal Setup

1. Installation:

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

   For dependency conflicts, use the shim:

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

2. Initialize Config: Generate a basic .php-cs-fixer.dist.php config file:

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

   This creates a Symfony-style config (recommended for Laravel projects).

3. First Run: Fix all files in your project:

   ./vendor/bin/php-cs-fixer fix src tests config
   

   Or dry-run with:

   ./vendor/bin/php-cs-fixer check src
   

Key First Use Cases

• Pre-commit Hook: Integrate with laravel-pint or Git hooks to auto-fix before commits.
• CI Pipeline: Run as a build step to enforce consistency:

  # .github/workflows/ci.yml
  - name: PHP-CS-Fixer
    run: ./vendor/bin/php-cs-fixer fix --dry-run --diff
  

• Onboarding: Run on new contributors' PRs via GitHub Actions.

Implementation Patterns

Workflows

1. Project-Wide Standardization: Use the @Symfony rule set (Laravel’s default) or @PhpCsFixer for stricter rules:

   // .php-cs-fixer.dist.php
   return PhpCsFixer\Config::create()
       ->setRules([
           '@Symfony' => true,
           'no_unused_imports' => true,
           'ordered_imports' => ['sort_algorithm' => 'alpha'],
       ]);
   

2. Laravel-Specific Customizations:

   • Artisan Commands: Add to composer.json scripts:

     "scripts": {
         "cs-fix": "php-cs-fixer fix src app config --allow-risky=yes"
     }
     

   • Service Providers: Extend config for use statements:

     'fully_qualified_strict_types' => true,
     'no_superfluous_phpdoc_tags' => ['remove_inheritdoc' => true],
     

3. Parallel Processing: Leverage the default parallel runner for large codebases (e.g., Laravel monorepos):

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

   • CI Optimization: Combine with --stop-on-violation to fail fast:

     ./vendor/bin/php-cs-fixer fix --stop-on-violation --parallel
     

4. Rule Sets for Migrations: Use @autoPHPMigration to modernize legacy PHP (e.g., mt_rand → random_int):

   return PhpCsFixer\Config::create()
       ->setRules([
           '@autoPHPMigration' => true,
           'random_api_migration' => true,
       ]);
   

Integration Tips

• IDE Sync: Configure PhpStorm’s "Reformat Code" to use PHP-CS-Fixer (Settings > Languages & Frameworks > PHP > Code Style > PHP-CS-Fixer).
• Laravel Pint Alternative: Replace laravel/pint with PHP-CS-Fixer for granular control:

  composer require --dev friendsofphp/php-cs-fixer --dev
  composer remove laravel/pint
  

• Custom Rules: Extend for Laravel-specific cases (e.g., Facade imports):

  'no_unused_imports' => true,
  'ordered_imports' => ['sort_algorithm' => 'custom', 'imports_order' => ['const', 'class', 'function']],
  

Gotchas and Tips

Pitfalls

1. Risky Rules:

   • Avoid @auto:risky in CI initially—test locally first. Example:

     ./vendor/bin/php-cs-fixer fix --rules=@auto:risky --dry-run
     

   • Laravel Gotcha: static_lambda may break legacy closures in service containers.

2. False Positives:

   • no_unused_imports: Exclude Laravel’s dynamic Facades:

     'no_unused_imports' => true,
     'exclude' => ['app/Providers/AppServiceProvider.php'],
     

   • ordered_imports: Conflicts with Laravel’s use Illuminate\Support\Facades\* patterns. Use:

     'ordered_imports' => ['sort_algorithm' => 'alpha', 'case_sensitive' => false],
     

3. Performance:

   • Parallel Mode: May fail on Windows or shared hosting. Fallback:

     ./vendor/bin/php-cs-fixer fix --parallel --processes=2
     

   • Memory Limits: Increase PHP memory for large projects:

     php -d memory_limit=2G ./vendor/bin/php-cs-fixer fix
     

4. Config Conflicts:

   • .php-cs-fixer.dist.php vs .php-cs-fixer.php: The latter overrides the former. Commit .dist.php to version control.
   • Merge Conflicts: Use --diff to debug:

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

Debugging

• Verbose Output:

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

• Rule-Specific Debugging: Disable a rule to isolate issues:

  'no_unused_imports' => false,
  

• Git Integration: Use git diff to review changes:

  git diff --name-only | xargs ./vendor/bin/php-cs-fixer fix --dry-run
  

Extension Points

1. Custom Rule Sets: Create a project-specific set in .php-cs-fixer.dist.php:

   return PhpCsFixer\Config::create()
       ->setRules([
           '@Symfony' => true,
           'laravel_rules' => true, // Custom rule (see below)
       ]);
   

   Define in composer.json:

   "extra": {
       "php-cs-fixer": {
           "rules": {
               "laravel_rules": {
                   "no_unused_imports": true,
                   "fully_qualified_strict_types": true,
                   "ordered_class_elements": ["order" => ["use_trait", "case"]]
               }
           }
       }
   }
   

2. PHPStan Integration: Combine with PHPStan for static analysis:

   composer require --dev phpstan/phpstan
   ./vendor/bin/phpstan analyse --level=5
   ./vendor/bin/php-cs-fixer fix
   

3. Editor Plugins:

   • VS Code: Install junstyle/vscode-php-cs-fixer for on-save fixing.
   • PhpStorm: Enable "On the fly" reformatting (Settings > Tools > PHP-CS-Fixer).

Laravel-Specific Tips

• Facade Imports: Suppress warnings for dynamic Facades:

  'no_unused_imports' => true,
  'exclude' => [
      'app/Providers/FacadeServiceProvider.php',
      'routes/web.php',
  ],
  

• Migration Files: Exclude from strict rules:

  'risky_rules' => ['@autoPHPMigration:risky' => true],
  'exclude' => ['database/migrations/*.php'],
  

• Blade Templates: Use --path-mode=overlay to skip:

  ./vendor/bin/php-cs-fixer fix --path-mode=overlay --exclude=resources/views