Getting Started

Minimal Steps to Begin

Install the package in your Laravel project:

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

Replace your existing .php-cs-fixer.php with the minimal config:

<?php
require 'vendor/autoload.php';

return (new PhpCsFixer\Config())
    ->setFinder(PhpCsFixer\Finder::create()->in(__DIR__.'/../src'))
    ->setRiskyAllowed(true)
    ->setRules(\Mfn\PhpCsFixer\Config::getRules());

Run PHP-CS-Fixer to validate or fix your code:
```
./vendor/bin/php-cs-fixer fix
```

First Use Case: Laravel Project Onboarding

For a new Laravel developer joining your team:

Step 1: Install the package in their local environment.
Step 2: Run php-cs-fixer fix to align their code with the team’s style.
Step 3: Integrate into their CI pipeline (e.g., GitHub Actions) to enforce consistency pre-commit or pre-merge.

Where to Look First

src/Config.php: Review the ruleset to understand the package’s opinionated choices (e.g., ordered_imports, nullable_type_declaration).
Release Notes: Check for Laravel-specific adjustments (e.g., Facade handling, Blade compatibility) in recent updates.

CI/CD Integration: Example workflow for GitHub Actions:

- name: Run PHP-CS-Fixer
  run: ./vendor/bin/php-cs-fixer fix --dry-run --diff

Implementation Patterns

Usage Patterns

1. Drop-in Replacement for Existing Configs

Replace your current .php-cs-fixer.php with the package’s rules:

return (new PhpCsFixer\Config())
    ->setFinder($finder) // Your existing finder logic
    ->setRiskyAllowed(true)
    ->setRules(\Mfn\PhpCsFixer\Config::getRules());

2. Partial Adoption (Selective Rules)

Extend the base rules while overriding specific ones:

$rules = \Mfn\PhpCsFixer\Config::getRules();
$rules['phpdoc_summary'] = false; // Disable if needed
$rules['strict_param'] = true;    // Override risky rules

return (new PhpCsFixer\Config())
    ->setRules($rules)
    ->setRiskyAllowed(true);

3. Laravel-Specific Workflows

Facade Handling: Disable native_function_invocation for Facade calls:

$rules['native_function_invocation']['include'] = [
    'compiler_optimized',
    '!Auth::user()', // Exclude Facade calls
];

Blade Template Rules: Exclude Blade files from PHP-CS-Fixer:

->setFinder(PhpCsFixer\Finder::create()
    ->in(__DIR__.'/../src')
    ->exclude(['resources/views'])
)

4. CI/CD Integration

GitHub Actions Example:

name: PHP-CS-Fixer
on: [push, pull_request]
jobs:
  fix:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: composer install
      - run: ./vendor/bin/php-cs-fixer fix --dry-run --diff

Pre-commit Hook: Use php-cs-fixer with tools like Husky or Laravel Pint for local enforcement.

Integration Tips

Combine with Laravel Pint: If using Pint, disable PHP-CS-Fixer for Blade files and let Pint handle them:

->setFinder(PhpCsFixer\Finder::create()
    ->in(__DIR__.'/../src')
    ->exclude(['resources/views', '*.blade.php'])
)

Custom Finder Logic: Target specific directories or file patterns:

->setFinder(PhpCsFixer\Finder::create()
    ->in(['src', 'app/Http/Controllers'])
    ->name('*.php')
    ->notName('*.blade.php')
)

Dry Runs in CI: Always use --dry-run --diff in CI to avoid unexpected changes:
```
./vendor/bin/php-cs-fixer fix --dry-run --diff
```

Gotchas and Tips

Pitfalls

Risky Rules Breaking Laravel Patterns:
- native_function_invocation: May break Facade calls (e.g., Auth::user()). Exclude them explicitly:
```
$rules['native_function_invocation']['include'] = ['compiler_optimized'];
```
- no_unused_imports: Could flag Laravel’s dynamic imports (e.g., use Illuminate\Support\Facades\Auth; even if Auth isn’t used directly). Disable if needed:
```
$rules['no_unused_imports'] = false;
```
- strict_param: May conflict with Laravel’s type-hinting conventions. Test thoroughly.
PHP Version Mismatches:
- Rules like nullable_type_declaration_for_default_null_value require PHP 8.4+. Ensure your CI and local environments match:
```
php -v  # Verify PHP version
```
Blade Template Conflicts:
- PHP-CS-Fixer may misinterpret Blade syntax (e.g., @foreach). Exclude Blade files:
```
->setFinder(PhpCsFixer\Finder::create()->exclude(['resources/views']))
```
Provenance Risks:
- The package lacks a license and has disabled GitHub issues. Audit src/Config.php before adoption, especially:
  - Check for hardcoded Laravel-specific rules.
  - Verify no malicious or deprecated rules are included.
Future-Dated Releases:
- The last release is dated 2026-03-26, which is unusual. Confirm the maintainer’s legitimacy or fork the package if needed.

Debugging Tips

Dry Run with Diff: Always use --dry-run --diff to preview changes:
```
./vendor/bin/php-cs-fixer fix --dry-run --diff
```
Log Level: Enable verbose logging to debug rule conflicts:
```
./vendor/bin/php-cs-fixer fix -v
```
Rule-Specific Debugging: Isolate problematic rules by disabling them one by one:
```
$rules['rule_name'] = false;
```

Extension Points

Custom Rule Overrides: Extend the base rules in your config:

$rules = \Mfn\PhpCsFixer\Config::getRules();
$rules['array_syntax'] = ['syntax' => 'short']; // Override to 'short'

Conditional Rules: Use environment variables to toggle rules:

$rules['strict_types'] = getenv('CS_FIXER_STRICT_TYPES') === 'true';

Fork and Maintain: If the package’s lack of visibility is a concern, fork it and customize:

git clone https://github.com/mfn/php-cs-fixer-config.git
composer require your-fork/php-cs-fixer-config

Laravel-Specific Quirks

Facade Calls: The native_function_invocation rule may misfire on Facade methods. Exclude them:

$rules['native_function_invocation']['exclude'] = [
    'Auth::*',
    'Cache::*',
    'Route::*',
];

Dependency Injection: Rules like ordered_imports may reorder Laravel’s Facade imports. Test with:
```
use Illuminate\Support\Facades\Auth;
use Illuminate\Support\Facades\Cache;
```
Ensure the order doesn’t break autoloading or IDE features (e.g., PHPStorm’s "Go to Implementation").
Blade Compatibility: PHP-CS-Fixer doesn’t handle Blade syntax well. Pair with Laravel Pint for Blade files:
```
./vendor/bin/pint --test
```

Performance Tips

Cache Results: Use PHP-CS-Fixer’s cache to speed up repeated runs:
```
./vendor/bin/php-cs-fixer fix --cache-file=.php-cs-fixer.cache
```
Parallel Processing: Enable parallel runs for large codebases:
```
./vendor/bin/php-cs-fixer fix --parallel
```
Exclude Tests: Skip testing directories to reduce runtime:
```
->setFinder
```

Php Cs Fixer Config Laravel Package