Php Cs Fixer Config Laravel Package

Getting Started

Minimal Setup for Laravel Developers

1. Install the package in your Laravel project:

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

2. Create the config file in your project root:

   touch .php-cs-fixer.dist.php
   

3. Paste the basic configuration (targets src/ and tests/ by default):

   <?php
   $finder = PhpCsFixer\Finder::create()
       ->in([__DIR__.'/src', __DIR__.'/tests']);
   
   return (new M6Web\CS\Config\BedrockStreaming())->setFinder($finder);
   

4. Add the cache file to .gitignore:

   .php-cs-fixer.cache
   

5. Verify installation with a dry run:

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

First Use Case: Pre-Commit Hook

Integrate with Laravel’s ecosystem by adding a pre-commit hook in .git/hooks/pre-commit:

#!/bin/sh
./vendor/bin/php-cs-fixer fix --dry-run --stop-on-violation

Make it executable:

chmod +x .git/hooks/pre-commit

Why? Blocks non-compliant code before it’s committed, reducing merge conflicts and CI failures.

Implementation Patterns

Daily Workflow for Laravel Developers

1. Local Development

• Fix issues interactively:

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

• Check changes without applying:

  make cs  # Uses the Makefile target (see below)
  

• Focus on specific files:

  ./vendor/bin/php-cs-fixer fix src/Http/Controllers/
  

2. Makefile Integration (Recommended)

Add this to your Laravel project’s Makefile (place in project root):

# PHP-CS-Fixer targets
cs:
	@echo "Checking PHP-CS-Fixer compliance..."
	./vendor/bin/php-cs-fixer fix --dry-run --stop-on-violation --diff

cs-fix:
	@echo "Fixing PHP-CS-Fixer issues..."
	./vendor/bin/php-cs-fixer fix

cs-ci:
	@echo "Running PHP-CS-Fixer in CI mode..."
	./vendor/bin/php-cs-fixer fix --dry-run --using-cache=no --verbose --rules=@BedrockStreaming

Usage:

make cs        # Check for violations (dry run)
make cs-fix    # Auto-fix all issues
make cs-ci     # CI-friendly check (no cache, verbose)

3. CI/CD Pipeline (GitHub Actions Example)

Add to .github/workflows/php-cs-fixer.yml:

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.4'
      - run: composer install
      - run: make cs-ci

Why? Ensures compliance before merging, even if local hooks are bypassed.

4. Customizing Rules for Laravel-Specific Needs

Extend the base config to add Laravel-specific rules (e.g., ordered imports):

<?php
$finder = PhpCsFixer\Finder::create()
    ->in([__DIR__.'/src', __DIR__.'/tests']);

$config = new class() extends M6Web\CS\Config\BedrockStreaming {
    public function getRules(): array {
        $rules = parent::getRules();
        $rules['ordered_imports'] = ['sort_algorithm' => 'alpha'];
        $rules['no_unused_imports'] = true;
        return $rules;
    }
};

return $config->setFinder($finder);

5. Pairing with Laravel Tools

• Laravel Forge/Envoyer: Run make cs-ci in deployment scripts to catch style issues early.
• Laravel Telescope: Use the --verbose flag to log violations to Telescope for team-wide visibility.
• Laravel Sail: Add the cs target to your docker-compose.yml services for containerized checks.

Gotchas and Tips

Common Pitfalls and Debugging

1. Rule Conflicts with Legacy Code

   • Issue: Rules like native_function_invocation or declare_strict_types may break older PHP versions.
   • Fix: Temporarily disable risky rules in CI:

     $config->setRiskyAllowed(false);
     

   • Tip: Use --allow-risky=yes in CLI for one-off fixes:

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

2. Cache Issues

   • Issue: Stale cache files cause false negatives in CI.
   • Fix: Force a fresh cache in CI:

     make cs-ci  # Uses `--using-cache=no`
     

   • Tip: Delete .php-cs-fixer.cache manually if corruption is suspected.

3. Performance in Large Repos

   • Issue: Slow execution on monorepos (e.g., Laravel + Vue/React).
   • Fix: Limit file scope:

     $finder->exclude(['node_modules', 'vendor', 'storage']);
     

   • Tip: Parallelize checks with --parallel (PHP-CS-Fixer 3.57+):

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

4. IDE Integration Quirks

   • Issue: IDEs (e.g., PHPStorm) may ignore .php-cs-fixer.dist.php.
   • Fix: Configure IDE to use the CLI tool:
     • PHPStorm: Settings > Tools > PHP > PHP Code Sniffer > Configuration File → Point to .php-cs-fixer.dist.php.
     • VSCode: Install the PHP-CS-Fixer extension and set php-cs-fixer.executablePath to ./vendor/bin/php-cs-fixer.

5. Git Hooks and Permissions

   • Issue: Pre-commit hooks fail due to permission errors.
   • Fix: Use a wrapper script or install hooks via composer:

     composer require --dev dealerdirect/phpcodesniffer-composer-installer
     

     Then add to composer.json:

     "extra": {
         "installer-paths": {
             "scripts/pre-commit.php": ["type:php-cs-fixer-hook"]
         }
     }
     

Pro Tips for Laravel Developers

1. Laravel-Specific Rule Overrides Add these to your custom config for Laravel projects:

   $rules['concat_space'] = ['spacing' => 'one']; // Laravel's `{{ }}` syntax
   $rules['blank_line_after_opening_tag'] = true;  // PSR-12 for Blade files
   

2. Exclude Vendor Files Avoid scanning Laravel’s vendor files (already compliant):

   $finder->exclude(['vendor']);
   

3. Team-Specific Customizations

   • For Blade Templates: Extend the config to target .blade.php files:

     $finder->in([__DIR__.'/resources/views']);
     

   • For Database Migrations: Add database/migrations to the finder:

     $finder->in([__DIR__.'/database/migrations']);
     

4. Debugging Rule Violations Use --verbose to see which rule triggered a violation:

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

   Output example:

   FIXER APPLIED: [native_function_invocation][src/ServiceProvider.php:42] Found native function call 'count' without parentheses.
   

5. PHP 8.4-Specific Rules Leverage PHP 8.4 features with these rules:

   $rules['php_unit_method_casing'] = ['case' => 'snake_case']; // For Pest/Laravel tests
   $rules['php_unit_test_class_requires_covers'] = true;         // Enforce test coverage
   

6. CI-Specific Optimizations

   • GitHub Actions: Cache Composer dependencies and PHP-CS-Fixer cache:

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

   • GitLab CI: Use artifacts to cache results between jobs.

7. Pairing with Other Tools

   • Pint: If using Laravel Pint, disable PHP-C