Php Cs Fixer Config Laravel Package

Getting Started

Minimal Setup

1. Install the package:

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

2. Integrate into your php-cs-fixer.neon or PHP config:

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

3. Run a test fix:

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

First Use Case

Use this package to standardize your team’s PHP code style without reinventing the wheel. Ideal for:

• New Laravel projects where PSR-12 + opinionated tweaks (e.g., strict imports, modern array syntax) are desired.
• Teams adopting php-cs-fixer for the first time but wanting a pre-configured, battle-tested setup.

Implementation Patterns

Workflows

1. Team Onboarding:

   • Add the package to composer.json under require-dev.
   • Update CI/CD pipelines to run php-cs-fixer on every PR (e.g., GitHub Actions):

     - name: Run PHP-CS-Fixer
       run: vendor/bin/php-cs-fixer fix --diff --dry-run
     

   • Document the config in CONTRIBUTING.md as a mandatory step.

2. Project-Specific Overrides:

   • Extend the rules in your config:

     $rules = \Mfn\PhpCsFixer\Config::getRules();
     $rules['phpdoc_align'] = ['align' => 'left']; // Override a specific rule
     

   • Use setFinder() to target specific paths (e.g., exclude tests):

     ->setFinder(\PhpCsFixer\Finder::create()->notPath(['tests']))
     

3. Laravel-Specific Integration:

   • Combine with laravel-pint (if using Pint) by aliasing php-cs-fixer in composer.json:

     "scripts": {
       "cs-fix": "php-cs-fixer fix",
       "pint": "pint"
     }
     

   • Use php-cs-fixer for legacy codebases and Pint for new projects (or vice versa).

Integration Tips

• Pre-commit Hooks: Use php-cs-fixer via a tool like pre-commit to auto-fix files:

  repos:
    - repo: local
      hooks:
        - id: php-cs-fixer
          name: PHP-CS-Fixer
          entry: vendor/bin/php-cs-fixer fix --allow-risky=yes
          language: system
          types: [php]
  

• IDE Support: Configure your IDE (PHPStorm/VSCode) to use this config for real-time feedback:
  • PHPStorm: Set php-cs-fixer as the code style tool in Settings > Tools > PHP > Code Sniffer.
  • VSCode: Use the PHP CS Fixer extension and point it to your config file.

Gotchas and Tips

Pitfalls

1. Risky Rules:

   • The config requires setRiskyAllowed(true). Be cautious with risky rules (e.g., no_unused_imports) as they may break functionality. Test thoroughly in a staging environment.
   • Debugging: Run with --dry-run first to preview changes:

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

2. Rule Conflicts:

   • Some rules (e.g., array_syntax, concat_space) may conflict with Laravel conventions. Override them explicitly:

     $rules['array_syntax'] = ['syntax' => 'short']; // Force short syntax
     

3. Performance:

   • Exclude large files/directories (e.g., vendor/, node_modules/) from the finder to speed up runs:

     ->setFinder(\PhpCsFixer\Finder::create()->exclude(['vendor', 'node_modules']))
     

Debugging

• Verbose Output: Use --verbose to diagnose issues:

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

• Rule-Specific Fixes: Isolate problematic rules by temporarily disabling them:

  $rules['no_unused_imports'] = false; // Disable to debug
  

Extension Points

1. Custom Rules: Merge additional rules from other configs (e.g., symfony):

   $rules = array_merge(
       \Mfn\PhpCsFixer\Config::getRules(),
       \Symfony\CS\Config::getRules()
   );
   

2. Dynamic Configs: Load rules conditionally based on environment (e.g., stricter rules for main branch):

   $rules = \Mfn\PhpCsFixer\Config::getRules();
   if (app()->environment('production')) {
       $rules['strict_param'] = true;
   }
   

3. Testing: Use php-cs-fixer in PHPUnit tests to validate style consistency:

   $this->assertFileEquals(
       __DIR__.'/expected_file.php',
       __DIR__.'/actual_file.php',
       'Files should match after CS fixing'
   );