Getting Started

Minimal Steps

Install the package in your Laravel project:

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

Configure PHP-CS-Fixer in your project’s root .php-cs-fixer.dist.php:

<?php
return (new Beste\PhpCsFixer\Config())
    ->setRules([
        '@Beste' => true, // Use the BESTE preset (PHP 8.1/8.2)
        'laravel:risky' => true, // Optional: Enable Laravel-specific rules
    ]);

Run PHP-CS-Fixer to auto-fix files:
```
vendor/bin/php-cs-fixer fix
```

Integrate with CI (e.g., GitHub Actions):

- name: Run PHP-CS-Fixer
  run: vendor/bin/php-cs-fixer fix --dry-run --diff --rules=@Beste

First Use Case

Standardize a Laravel project’s code style by:

Enforcing consistent use statement ordering (e.g., grouped by type: Framework, Laravel, Third-party, Local).
Aligning PHPDoc formatting (left-aligned, null types last).
Fixing semicolon placement (e.g., chained method calls on new lines).
Validating Laravel-specific syntax (e.g., Artisan commands, Blade templates).

Implementation Patterns

Workflows

Project Setup

Add to composer.json under require-dev:
```
"beste/php-cs-fixer-config": "^3.3"
```

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

return (new Beste\PhpCsFixer\Config())
    ->setRules([
        '@Beste/Php82' => true, // PHP 8.2 preset
        'ordered_imports' => true,
        'no_unused_imports' => true,
    ]);

Laravel-Specific Customization

Override rules for Laravel files (e.g., Blade templates):

->setFinder(
    (new PhpCsFixer\Finder())
        ->in(__DIR__)
        ->exclude('vendor')
        ->name('*.php')
        ->notName('*.blade.php') // Exclude Blade files
)
->setRules([
    'blank_line_after_opening_tag' => true, // For Blade
]);

CI/CD Integration

GitHub Actions Example:

jobs:
  php-cs-fixer:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: composer install
      - run: vendor/bin/php-cs-fixer fix --dry-run --diff --rules=@Beste/Php82

Team Onboarding
- Add a Makefile target for new developers:
```
fix-style:
    @echo "Running PHP-CS-Fixer..."
    vendor/bin/php-cs-fixer fix --rules=@Beste/Php82
```
- Document the preset choice (e.g., Php82 for PHP 8.2 projects) in CONTRIBUTING.md.

Integration Tips

Laravel Artisan Commands: Use the laravel:risky preset to handle dynamic use statements (e.g., use App\Commands\{$command}).
Blade Templates: Exclude .blade.php files from auto-fixing unless you’ve configured Blade-specific rules.
Monorepos: Centralize the config in a shared package (e.g., @your-org/php-cs-fixer-config) and require it across projects.

Pre-commit Hooks: Use php-cs-fixer with husky or pre-commit to block style violations early:

composer require --dev php-cs-fixer
npx husky add .husky/pre-commit "vendor/bin/php-cs-fixer fix --dry-run --diff"

Gotchas and Tips

Pitfalls

Preset Mismatch
- Issue: Using Php81 preset in a PHP 8.2 project may miss rules like match_using_similar_syntax.
- Fix: Always align the preset with your PHP version (e.g., @Beste/Php82 for PHP 8.2).
Deprecated Rules
- Issue: The package replaces deprecated rules (e.g., no_spaces_inside_parenthesis → spaces_inside_parentheses), but some Laravel-specific rules may lag.
- Fix: Check the changelog for replacements and update your config accordingly.

Blade Template Handling

Issue: Blade files (.blade.php) may not be formatted correctly by default.

Fix: Explicitly include/exclude them in the Finder:

->setFinder(
    (new PhpCsFixer\Finder())
        ->in(__DIR__)
        ->name('*.php')
        ->exclude('resources/views') // Or include with Blade rules
)

Performance with Large Codebases
- Issue: Running php-cs-fixer on monorepos or large projects can be slow.
- Fix: Use parallel processing:
```
vendor/bin/php-cs-fixer fix --parallel
```
  Or limit scope:
```
vendor/bin/php-cs-fixer fix app/ src/
```
CI Flakiness
- Issue: Dry-run checks may fail intermittently due to line-ending differences (e.g., CRLF vs. LF).
- Fix: Normalize line endings in CI:
```
- run: git config --global core.autocrlf input
```

Debugging

Dry-Run Diffs: Always use --dry-run --diff to preview changes:

vendor/bin/php-cs-fixer fix --dry-run --diff --rules=@Beste/Php82

Rule-Specific Debugging: Isolate problematic rules by testing one at a time:
```
vendor/bin/php-cs-fixer fix --rules=ordered_imports
```
Logging: Enable verbose output for troubleshooting:
```
vendor/bin/php-cs-fixer fix -v
```

Extension Points

Custom Rulesets Extend the base config for project-specific needs:

return (new Beste\PhpCsFixer\Config())
    ->setRules([
        '@Beste/Php82' => true,
        'line_ending' => true, // Force LF
        'array_syntax' => ['syntax' => 'short'], // Prefer `[]` over `array()`
    ]);

Laravel-Specific Overrides Target Laravel files (e.g., migrations, commands) with custom rules:

->setRules([
    'files' => [
        'database/migrations/*' => [
            'no_unused_imports' => false, // Disable for migrations
        ],
    ],
]);

PHPCS-Fixer Version Pinning Avoid conflicts by pinning the version in composer.json:
```
"php-cs-fixer": "^3.10",
"beste/php-cs-fixer-config": "^3.3"
```

Shared Config for Monorepos Create a shared package (e.g., @your-org/coding-standards) with:

// packages/coding-standards/config/php-cs-fixer.php
return (new Beste\PhpCsFixer\Config())
    ->setRules([
        '@Beste/Php82' => true,
        // Shared rules...
    ]);

Require it in child projects:

"@your-org/coding-standards": "^1.0"

Pro Tips

Laravel Artisan Integration: Add a custom Artisan command to run PHP-CS-Fixer:

php artisan make:command FixStyle

// app/Console/Commands/FixStyle.php
public function handle()
{
    $this->callSilently('php-cs-fixer', ['fix', '--rules=@Beste/Php82']);
}

Pre-commit Hooks: Use php-cs-fixer with pre-commit:

composer require --dev php-cs-fixer
npx pre-commit install

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: php-cs-fixer
        name: PHP-CS-Fixer
        entry: vendor/bin/php-cs-fixer fix --dry

Php Cs Fixer Config Laravel Package