Php Cs Fixer Config Laravel Package

Getting Started

Minimal Setup

1. Install the package via Composer in your Laravel project:

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

2. Reference the config in your project’s .php-cs-fixer.dist.php:

   <?php
   use Diablomedia\PhpCsFixerConfig\Config;
   
   $config = Config::laravel();
   $config->setRules([
       // Override or extend rules here if needed
       '@PSR12' => true,
   ]);
   return $config;
   

3. Run PHP-CS-Fixer to auto-fix files:

   vendor/bin/php-cs-fixer fix
   

First Use Case

• Standardize Laravel project formatting (e.g., align use statements, PSR-12 compliance) across a team.
• Integrate with CI/CD (e.g., GitHub Actions) to enforce consistency pre-merge:

  # Example GitHub Actions step
  - name: Run PHP-CS-Fixer
    run: vendor/bin/php-cs-fixer fix --dry-run --diff
  

Implementation Patterns

Workflows

1. Team-Wide Adoption

   • Store the package in a private Composer repository (e.g., GitHub Packages) to enforce a single source of truth for all projects.
   • Update the package version once in the root repository; child projects inherit changes via Composer.

2. Project-Specific Overrides

   • Extend the base config in .php-cs-fixer.dist.php:

     $config = Config::laravel();
     $config->setRules([
         '@Symfony' => true, // Add Symfony-specific rules
         'no_unused_imports' => true,
     ]);
     

   • Use --allow-risky=yes for experimental rules (e.g., @PHP80Migration).

3. CI Integration

   • Fail builds on style violations (dry-run mode):

     vendor/bin/php-cs-fixer fix --dry-run --diff --stop-on-violation
     

   • Cache PHP-CS-Fixer results in CI to avoid redundant checks:

     - uses: actions/cache@v3
       with:
         path: vendor
         key: ${{ runner.os }}-php-cs-fixer-${{ hashFiles('**/composer.lock') }}
     

4. Laravel-Specific Patterns

   • Ignore vendor files by default (already handled by the package).
   • Focus on critical files (e.g., app/, config/, routes/) in CI:

     vendor/bin/php-cs-fixer fix app/ config/ routes/ --dry-run
     

Gotchas and Tips

Pitfalls

1. Rule Conflicts

   • Avoid mixing @PSR12 and @Symfony presets without testing; some rules may overlap or contradict.
   • Debug tip: Run with --verbose to see which rules are applied:

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

2. Performance in Large Projects

   • Exclude unnecessary paths (e.g., storage/, bootstrap/cache/) to speed up runs:

     $config->setFinder()
             ->exclude(['storage/', 'bootstrap/cache/']);
     

3. Version Skew Issues

   • Ensure all projects using the shared config pin the package version in composer.json to avoid unexpected rule changes:

     "require-dev": {
         "diablomedia/php-cs-fixer-config": "1.2.0"
     }
     

4. IDE Integration

   • Some IDEs (e.g., PHPStorm) may not auto-detect the config. Manually link the .php-cs-fixer.dist.php file in IDE settings under "PHP > Code Style > PHP-CS-Fixer".

Debugging

• Dry-run with diff:

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

• Test specific files:

  vendor/bin/php-cs-fixer fix app/Models/User.php
  

• List available rules:

  vendor/bin/php-cs-fixer --dump-rules
  

Extension Points

1. Custom Presets

   • Create a project-specific preset by extending the base config:

     $config = Config::laravel();
     $config->setRules([
         '@CustomPreset' => [
             'no_superfluous_phpdoc_tags' => true,
             'ordered_imports' => ['sort_algorithm' => 'alpha'],
         ],
     ]);
     

2. Dynamic Configs

   • Use environment variables to toggle rules (e.g., for legacy code):

     $config->setRules([
         'concat_space' => getenv('ENABLE_CONCAT_SPACE') === 'true',
     ]);
     

3. Git Hooks

   • Add a pre-commit hook to auto-fix files (use php-cs-fixer’s --allow-risky cautiously):

     # .git/hooks/pre-commit
     #!/bin/sh
     vendor/bin/php-cs-fixer fix --allow-risky --diff
     

4. Parallel Processing

   • Speed up large codebases with --parallel (requires PHP 7.4+):

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