Php Cs Fixer Config Laravel Package

Getting Started

Minimal Steps

1. Installation Add the package to your project via Composer:

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

2. Configuration Copy the default config file to your project’s root:

   cp vendor/azuyalabs/php-cs-fixer-config/php-cs-fixer.dist.php .php-cs-fixer.dist.php
   

   Ensure it’s included in .gitignore if not already.

3. First Use Case Run PHP CS Fixer on your project:

   vendor/bin/php-cs-fixer fix --rules=@azuyalabs
   

   Verify changes with a dry run:

   vendor/bin/php-cs-fixer fix --dry-run --rules=@azuyalabs
   

4. CI/CD Integration Add a script to your composer.json:

   "scripts": {
       "cs-fix": "php-cs-fixer fix --rules=@azuyalabs --allow-risky=yes"
   }
   

   Run it in your CI pipeline (e.g., GitHub Actions) to enforce consistency.

Implementation Patterns

Workflows

1. Team Onboarding

   • Share the config file (php-cs-fixer.dist.php) in your team’s documentation or repo’s CONTRIBUTING.md.
   • Example snippet for IDE setup (e.g., PHPStorm):

     # .phpstorm.meta.php
     rules:
       - name: PHP CS Fixer
         level: error
         paths:
           - "."
         executable: vendor/bin/php-cs-fixer
         arguments: "--rules=@azuyalabs --dry-run"
     

2. Project-Specific Customization Extend the base config by merging rules:

   // .php-cs-fixer.dist.php
   return (new PhpCsFixer\Config())
       ->setRules([
           '@azuyalabs' => true,
           'no_unused_imports' => true, // Add custom rules
           'concat_space' => ['spacing' => 'one'], // Override existing
       ]);
   

3. Laravel-Specific Integration

   • Artisan Command: Create a custom command to auto-fix files on demand:

     // app/Console/Commands/FixCs.php
     namespace App\Console\Commands;
     use Illuminate\Console\Command;
     class FixCs extends Command {
         protected $signature = 'cs:fix';
         public function handle() {
             $this->call('vendor:publish', ['--tag' => 'php-cs-fixer-config']);
             $this->call('php-cs-fixer', ['fix', '--rules=@azuyalabs']);
         }
     }
     

   • Register in app/Console/Kernel.php:

     protected $commands = [
         Commands\FixCs::class,
     ];
     

4. Pre-Commit Hook Use husky or pre-commit to run checks before commits:

   echo 'vendor/bin/php-cs-fixer fix --rules=@azuyalabs --dry-run --diff' >> .git/hooks/pre-commit
   chmod +x .git/hooks/pre-commit
   

Gotchas and Tips

Pitfalls

1. Rule Conflicts

   • Some rules (e.g., array_syntax, class_attributes) may conflict with Laravel’s coding standards.
   • Fix: Explicitly override conflicting rules in your config:

     'array_syntax' => ['syntax' => 'short'], // Force short syntax
     

2. Performance

   • Running PHP CS Fixer on large codebases (e.g., monorepos) can be slow.
   • Tip: Use --parallel for multi-core processing:

     vendor/bin/php-cs-fixer fix --rules=@azuyalabs --parallel
     

3. IDE Integration Issues

   • Some IDEs (e.g., VSCode) may not respect the config file path.
   • Fix: Ensure the config is named .php-cs-fixer.dist.php and placed in the project root.

4. Risky Rules

   • Rules like no_unused_imports or simplified_null_return can break functionality.
   • Tip: Use --allow-risky=yes cautiously and review changes:

     vendor/bin/php-cs-fixer fix --rules=@azuyalabs --allow-risky=yes --diff
     

Debugging

1. Dry Run Mismatches If changes appear in dry-run but not in fix, check:

   • File permissions.
   • .gitignore exclusions (e.g., vendor/, node_modules/).
   • Custom path filters in the config.

2. Rule-Specific Errors

   • Use --verbose to debug rule application:

     vendor/bin/php-cs-fixer fix --rules=@azuyalabs --verbose
     

Extension Points

1. Custom Rule Sets Create a project-specific rule set by extending the base config:

   // php-cs-fixer.dist.php
   return (new PhpCsFixer\Config())
       ->setRules([
           '@azuyalabs' => true,
           '@PhpCsFixer' => true, // Include default rules
           'risky_nullable_type_declaration_for_php7' => false, // Disable risky rules
       ]);
   

2. Path Filtering Target specific directories or files:

   ->setFinder(
       PhpCsFixer\Finder::create()
           ->in(__DIR__)
           ->exclude('tests')
           ->name('*.php')
           ->notName('*.blade.php')
   )
   

3. CI-Specific Configs Use environment variables to switch configs:

   $rules = getenv('CI') ? ['@azuyalabs', 'no_unused_imports'] : ['@azuyalabs'];
   return (new PhpCsFixer\Config())->setRules($rules);
   

4. Laravel Mix/Webpack Add a script to auto-fix during npm run dev:

   // webpack.mix.js
   mix.webpackConfig({
       plugins: [
           new FixCsPlugin() // Hypothetical plugin; use a custom script instead
       ]
   });
   

   Alternative: Use a post-build hook in package.json:

   "scripts": {
       "dev": "mix && composer cs-fix",
       "cs-fix": "php-cs-fixer fix --rules=@azuyalabs"
   }