Php Cs Fixer Config Laravel Package

Getting Started

1. Install the package in your Laravel project:

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

2. Configure PHP-CS-Fixer in your project by creating a .php-cs-fixer.php file with one of the Laravel-specific presets:

   <?php
   use Beste\PhpCsFixer\RuleSet\Php82;
   
   return (new Php82())
       ->setUsingCache(true)
       ->setRiskyAllowed(true);
   

   Replace Php82 with Php81 if using PHP 8.1 or Beste\PhpCsFixer\RuleSet\Laravel for Laravel-specific rules.

3. Test the configuration with a dry run:

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

4. Integrate with CI (e.g., GitHub Actions) to enforce style checks:

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

Implementation Patterns

1. Laravel-Specific Workflows

• Artisan Integration: Create a custom Artisan command to run PHP-CS-Fixer:

  php artisan make:command FixCs
  

  // app/Console/Commands/FixCs.php
  public function handle()
  {
      $this->call('php-cs-fixer', [
          'command' => 'fix',
          '--path-mode' => 'intersection',
          '--rules' => '@Beste',
      ]);
  }
  

  Register it in app/Console/Kernel.php and run with:

  php artisan fix:cs
  

• Laravel Mix Hooks: Auto-fix PHP files during build:

  // webpack.mix.js
  mix.postCss('resources/css/app.css', 'public/css', [
      // ...
  ])
  .then(() => {
      require('child_process').execSync('vendor/bin/php-cs-fixer fix app/ --dry-run');
  });
  

2. Rule Customization

• Override specific rules while keeping the base config:

  return (new Php82())
      ->setRules([
          '@PSR12' => true,
          'yoda_style' => ['equal' => false, 'identical' => false, 'less_and_greater' => false],
          'no_unused_imports' => true,
      ]);
  

• Project-specific exclusions:

  ->setFinder(
      \PhpCsFixer\Finder::create()
          ->in(__DIR__.'/../app')
          ->exclude('vendor')
          ->exclude('storage')
          ->exclude('tests/Fixtures')
  )
  

3. CI/CD Patterns

• GitHub Actions Example:

  name: PHP-CS-Fixer
  on: [push, pull_request]
  jobs:
    fix:
      runs-on: ubuntu-latest
      steps:
        - uses: actions/checkout@v4
        - uses: shivammathur/setup-php@v2
          with:
            php-version: '8.2'
        - run: composer install --dev
        - run: vendor/bin/php-cs-fixer fix --dry-run --diff
  

• GitLab CI:

  php-cs-fixer:
    stage: test
    script:
      - vendor/bin/php-cs-fixer fix --dry-run --diff
    rules:
      - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
  

4. Monorepo Support

• Root-level configuration: Install the package in the root composer.json and reference it in each package’s .php-cs-fixer.php:

  // packages/my-package/.php-cs-fixer.php
  return (new \Beste\PhpCsFixer\RuleSet\Php82())
      ->setPathMode('intersection')
      ->setRules([
          'native_function_invocation' => ['include' => ['@compiler_optimized']],
      ]);
  

Gotchas and Tips

Pitfalls

1. PHP Version Mismatch:

   • Ensure your project’s PHP version aligns with the preset (e.g., Php82 requires PHP 8.2+).
   • Fix: Use Php81 for PHP 8.1 or adjust composer.json:

     "config": {
         "platform-check": false
     }
     

2. Deprecated Rules:

   • The package replaces deprecated rules (e.g., no_spaces_inside_parenthesis → spaces_inside_parentheses).
   • Fix: Run vendor/bin/php-cs-fixer fix --allow-risky=yes to auto-migrate.

3. Laravel-Specific False Positives:

   • Rules like native_function_invocation may misflag Laravel’s dynamic use statements (e.g., use App\Models\${model}).
   • Fix: Exclude problematic files or override the rule:

     ->setRules([
         'native_function_invocation' => ['include' => ['@compiler_optimized'], 'exclude' => ['App\Models\\']],
     ]);
     

4. Performance in Large Codebases:

   • PHP-CS-Fixer can slow down CI for monorepos with 10K+ files.
   • Fix: Use --parallel or limit paths:

     vendor/bin/php-cs-fixer fix --parallel --path-mode=intersection
     

Debugging Tips

• Dry Run with Diff:

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

  Reveals exactly what will change.

• Rule-Specific Debugging: Disable all rules except one to isolate issues:

  ->setRules(['rule_name' => true])
  

• Cache Issues: Clear the cache if rules seem ignored:

  vendor/bin/php-cs-fixer fix --no-cache
  

Extension Points

1. Custom Presets: Extend the base presets for project needs:

   // app/Rules/LaravelCustom.php
   namespace App\Rules;
   
   use Beste\PhpCsFixer\RuleSet\Php82;
   
   class LaravelCustom extends Php82
   {
       public function __construct()
       {
           $this->setRules([
               'array_syntax' => ['syntax' => 'short'],
               'concat_space' => ['spacing' => 'one'],
           ]);
       }
   }
   

2. Dynamic Rule Loading: Load rules from a config file (e.g., config/cs-fixer.php):

   $config = require __DIR__.'/../../config/cs-fixer.php';
   return (new Php82())->setRules($config['rules']);
   

3. CI-Specific Overrides: Use environment variables to toggle strictness:

   $strict = getenv('CS_FIXER_STRICT') === 'true';
   return (new Php82())->setRules(['strict' => $strict ? '@Beste' : '@PSR12']);
   

Pro Tips

• Pre-commit Hooks: Use lint-staged to auto-fix staged PHP files:

  {
    "lint-staged": {
      "*.php": [
        "vendor/bin/php-cs-fixer fix --path-mode=relative --allow-risky=yes"
      ]
    }
  }
  

• IDE Integration: Configure PHPStorm to use the same rules:

  • Go to Settings > Editor > Code Style > PHP.
  • Click ... > Import Scheme and select PHP-CS-Fixer (if available) or manually map rules.

• Team Onboarding: Document the preset in CONTRIBUTING.md:

  ## Code Style
  We use `beste/php-cs-fixer-config` with the `Php82` preset. Run:
  ```bash
  composer require --dev beste/php-cs-fixer-config
  vendor/bin/php-cs-fixer fix