Php Cs Fixer Styleci Bridge Laravel Package

Getting Started

Minimal Setup

1. Install the package via Composer:

   composer require --dev sllh/php-cs-fixer-styleci-bridge
   

2. Ensure .styleci.yml exists in your project root (required for config generation). Example minimal config:

   presets: [styleci]
   rules:
     braces: ~
     linebreak_after_opening_tag: true
   

3. Generate PHP-CS-Fixer config in a Laravel task (e.g., php artisan cs:generate):

   // app/Console/Commands/GenerateCsFixerConfig.php
   use Sllh\PhpCsFixerStyleciBridge\StyleciToPhpCsFixer;
   
   public function handle()
   {
       $styleciConfig = include __DIR__.'/../../.styleci.yml';
       $phpCsFixerConfig = StyleciToPhpCsFixer::convert($styleciConfig);
       file_put_contents(base_path('.php-cs-fixer.dist.php'), '<?php return '.var_export($phpCsFixerConfig, true).';');
   }
   

4. Run PHP-CS-Fixer with the generated config:

   vendor/bin/php-cs-fixer fix
   

First Use Case

Use this package to eliminate duplicate config maintenance between StyleCI (for CI/CD) and PHP-CS-Fixer (for local development). Ideal for teams already using StyleCI but needing local fixes.

Implementation Patterns

Workflow Integration

1. CI/CD Pipeline:

   • Commit .styleci.yml to version control.
   • Use this package in a build step to auto-generate .php-cs-fixer.dist.php before running tests or fixes.
   • Example GitHub Actions step:

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

2. Local Development:

   • Add a composer script to auto-generate the config on install:

     {
       "scripts": {
         "post-install-cmd": [
           "php artisan cs:generate"
         ]
       }
     }
     

   • Use Laravel Forge/Envoyer to deploy the generated config alongside your app.

3. Custom Rules Handling:

   • Extend the converter to handle StyleCI-specific rules not mapped to PHP-CS-Fixer v1:

     // app/Providers/AppServiceProvider.php
     use Sllh\PhpCsFixerStyleciBridge\StyleciToPhpCsFixer;
     
     public function boot()
     {
         StyleciToPhpCsFixer::addCustomRule('custom_rule', function ($value) {
             return ['CustomRule' => ['option' => $value]];
         });
     }
     

Laravel-Specific Tips

• Service Provider Binding: Bind the converter as a singleton for reusable access:

  $this->app->singleton('styleci-converter', function ($app) {
      return new StyleciToPhpCsFixer();
  });
  

• Artisan Command: Register the command in AppServiceProvider:

  Artisan::register(new \App\Console\Commands\GenerateCsFixerConfig());
  

Gotchas and Tips

Pitfalls

1. PHP-CS-Fixer v2 Incompatibility:

   • This package only works with PHP-CS-Fixer v1. If you upgrade, the generated config will break.
   • Workaround: Pin PHP-CS-Fixer to v1.x in composer.json:

     "require-dev": {
       "php-cs-fixer": "^1.20"
     }
     

2. Missing Rule Mappings:

   • Some StyleCI rules (e.g., align_double_arrow) have no direct PHP-CS-Fixer equivalent.
   • Debugging: Check the StyleCI docs and PHP-CS-Fixer rules for manual overrides.

3. Preset Conflicts:

   • StyleCI presets (e.g., styleci) may not align with PHP-CS-Fixer presets.
   • Fix: Override the generated config:

     $config = StyleciToPhpCsFixer::convert($styleciConfig);
     $config['rules']['array_syntax'] = ['syntax' => 'short'];
     

Debugging

• Verify Input/Output: Dump the generated config to debug mismatches:

  $config = StyleciToPhpCsFixer::convert($styleciConfig);
  var_dump($config);
  

• Check for Deprecations: Use --allow-risky=yes with PHP-CS-Fixer v1 to bypass warnings:

  vendor/bin/php-cs-fixer fix --allow-risky=yes
  

Extension Points

1. Custom Rule Handlers: Extend the converter for unsupported rules:

   StyleciToPhpCsFixer::addCustomRule('phpdoc_align', function ($value) {
       return ['phpdoc_align' => ['align' => $value]];
   });
   

2. Post-Processing: Modify the generated config after conversion:

   $config = StyleciToPhpCsFixer::convert($styleciConfig);
   $config['finder']->exclude(['vendor/', 'storage/']);
   

3. Caching: Cache the generated config to avoid regenerating on every run:

   $cacheKey = 'php-cs-fixer-config';
   $config = Cache::remember($cacheKey, now()->addHours(1), function () {
       return StyleciToPhpCsFixer::convert($styleciConfig);
   });
   

Config Quirks

• Indentation Sensitivity: YAML indentation in .styleci.yml must be exact (2 spaces). Use a linter like yamllint to validate.
• Boolean Values: StyleCI uses ~ for "disabled" (e.g., braces: ~), but PHP-CS-Fixer expects false. The package handles this, but verify with:

  var_dump(StyleciToPhpCsFixer::convert(['rules' => ['braces' => '~']]));