Php Cs Fixer Config Laravel Package

Getting Started

Minimal Setup

1. Install the package in your Laravel project:

   composer require --dev mfn/php-cs-fixer-config
   

2. Replace your existing php-cs-fixer rules with the package’s config in php-cs-fixer.dist.php:

   <?php
   require 'vendor/autoload.php';
   
   return (new PhpCsFixer\Config())
       ->setRules(\Mfn\PhpCsFixer\Config::getRules())
       ->setRiskyAllowed(true)
       ->setFinder(
           PhpCsFixer\Finder::create()
               ->in(__DIR__.'/../src')
               ->exclude('vendor')
       );
   

3. Test with a dry run to preview changes:

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

First Use Case: Enforcing Consistent Formatting

Use this package to standardize code formatting across your team without manual rule curation. Ideal for:

• New Laravel projects where you want to avoid PSR-12’s generic defaults.
• Legacy codebases needing a modern, opinionated cleanup (e.g., trailing commas, import ordering).
• CI/CD pipelines to block formatting violations pre-commit.

Implementation Patterns

Core Workflow: Integration with Laravel

1. Replace Existing Config: Delete custom php-cs-fixer rules and replace them with:

   $rules = \Mfn\PhpCsFixer\Config::getRules();
   

   This ensures consistency across all projects using the package.

2. Laravel-Specific Adjustments: Override rules for Laravel patterns (e.g., facades, Blade) by merging with the package’s rules:

   $rules = \Mfn\PhpCsFixer\Config::getRules();
   $rules['no_unused_imports'] = 'false'; // Disable for facades
   return (new PhpCsFixer\Config())->setRules($rules)->setRiskyAllowed(true);
   

3. CI/CD Integration: Add to your GitHub Actions workflow (.github/workflows/php-cs-fixer.yml):

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

Common Patterns

Laravel-Specific Tips

• Facades: The package’s ordered_imports may conflict with Laravel’s use App\Facades;. Override:

  $rules['ordered_imports'] = ['case_sensitive' => false, 'sort_algorithm' => 'alpha'];
  

• Blade Files: Exclude from checks or use a custom finder:

  ->setFinder(Finder::create()->in(['src', 'app'])->exclude(['resources/views']))
  

• Dynamic Properties: If using PHP 8.2+, disable property_type for dynamic properties:

  $rules['property_type'] = ['skip_missing_properties' => true];
  

Gotchas and Tips

Pitfalls

1. setRiskyAllowed(true):

   • Issue: Enables aggressive rules like native_function_invocation (e.g., str_replace → str_replace()).
   • Fix: Test with --dry-run first. Override risky rules:

     $rules['native_function_invocation'] = ['include' => ['str_replace']];
     

2. Laravel Facade Conflicts:

   • Issue: no_unused_imports may flag use App\Facades; as unused.
   • Fix: Whitelist facade imports:

     $rules['no_unused_imports'] = ['false', 'App\Facades.*'];
     

3. Blade Template False Positives:

   • Issue: PHP rules may misapply to Blade syntax (e.g., @foreach).
   • Fix: Exclude Blade files:

     ->setFinder(Finder::create()->exclude(['*.blade.php']))
     

4. PHP 8.4 Nullable Types:

   • Issue: nullable_type_declaration may break PHP <8.4 code.
   • Fix: Disable for older PHP versions:

     if (version_compare(PHP_VERSION, '8.4.0') < 0) {
         $rules['nullable_type_declaration'] = false;
     }
     

5. Deprecated Rules:

   • Issue: The package replaces deprecated rules (e.g., no_trailing_comma_in_list_call → no_trailing_comma_in_singleline).
   • Fix: Ensure your project’s php-cs-fixer is v3.11+ to avoid conflicts.

Debugging Tips

• Dry Run: Always test changes first:

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

• Rule-Specific Fixes: Isolate problematic rules:

  ./vendor/bin/php-cs-fixer fix --rules=ordered_imports --dry-run
  

• Custom Config: Create a php-cs-fixer.custom.php to override rules:

  $rules = \Mfn\PhpCsFixer\Config::getRules();
  $rules['array_indentation'] = 'true';
  return (new PhpCsFixer\Config())->setRules($rules);
  

Extension Points

1. Override Rules: Merge with the package’s rules to customize:

   $rules = \Mfn\PhpCsFixer\Config::getRules();
   $rules['phpdoc_align'] = ['align' => 'left'];
   

2. Add Custom Rules: Extend the ruleset dynamically:

   $rules = \Mfn\PhpCsFixer\Config::getRules();
   $rules['custom_rule'] = ['value' => 'config'];
   

3. Conditional Rules: Use PHP logic to enable/disable rules based on environment:

   $rules = \Mfn\PhpCsFixer\Config::getRules();
   if (app()->environment('local')) {
       $rules['no_unused_imports'] = false;
   }
   

Pro Tips

• Laravel Forge/Envoyer: Add the package to your composer.json and run php-cs-fixer in deployment scripts.
• PestPHP: Combine with Pest’s --minimal flag for faster tests:

  ./vendor/bin/pest --minimal && ./vendor/bin/php-cs-fixer fix
  

• VS Code Integration: Use the PHP CS Fixer extension with this config for real-time feedback.
• Team Onboarding: Document the package’s rules in your CONTRIBUTING.md to reduce ramp-up time. Example:

  ## Code Style
  We use [mfn/php-cs-fixer-config](https://github.com/mfn/php-cs-fixer-config) for consistent formatting.
  Run `composer fix` to auto-format your code.