Php Cs Fixer Config Laravel Package

Technical Evaluation

Architecture fit

• Laravel-specific presets: The package’s laravel and laravel-strict rulesets are explicitly designed for Laravel’s syntax (e.g., Artisan commands, Blade templates, dynamic use statements), reducing the need for custom configurations in Laravel projects. This aligns with Laravel’s ecosystem and avoids reinventing wheel for common formatting needs.
• PHP-CS-Fixer v3.x compatibility: The package is built on modern PHP-CS-Fixer standards (v3.x), ensuring compatibility with Laravel’s latest features (e.g., PHP 8.4, enums, readonly properties). The presets abstract away version-specific quirks, simplifying maintenance.
• Dependency model: The package avoids direct friendsofphp/php-cs-fixer dependencies, adhering to PHP-CS-Fixer’s recommended practices. This reduces version conflicts and aligns with Laravel’s Composer-based dependency management.
• Extensibility: The base config can be extended or overridden per project, allowing teams to enforce shared standards while accommodating project-specific needs (e.g., custom line lengths, PHPDoc rules).

Integration feasibility

• Low-risk adoption: The package’s presets are designed for drop-in usage with minimal configuration. Laravel projects can replace or extend existing .php-cs-fixer.php files without breaking changes (post-3.0.0).
• Framework awareness: Rulesets account for Laravel-specific patterns (e.g., use App\Models\${model} dynamic imports, Blade syntax in .blade.php files). This reduces the need for manual rule tweaking.
• Composer integration: The package is a dev dependency, ensuring it’s isolated from production environments and version-managed alongside other tools (e.g., Pest, Laravel Pint).

Technical risk

1. Preset strictness:
   • The laravel-strict preset may enforce unexpected rules (e.g., line length limits, PHPDoc alignment) that conflict with legacy codebases. Mitigation: Run php-cs-fixer fix --dry-run before full adoption.
   • Key question: Are there known false positives for Laravel’s dynamic syntax (e.g., use App\${namespace}\Model)?
2. PHP-CS-Fixer version lock:
   • The package requires PHP-CS-Fixer v3.x, which may necessitate upgrades in older Laravel projects (e.g., pre-8.x). Mitigation: Test with composer require friendsofphp/php-cs-fixer:^3.0 first.
3. Performance overhead:
   • Large codebases (e.g., monorepos with 10K+ files) may experience slowdowns during CI runs. Mitigation: Benchmark with --parallel and adjust CI cache strategies.
4. Blade template support:
   • While the package claims Laravel support, Blade-specific rules (e.g., @foreach formatting) may not be fully covered. Mitigation: Validate with a sample .blade.php file.
5. Deprecated rule replacements:
   • The changelog shows replacements for deprecated rules (e.g., function_typehint_space → type_declaration_spaces), but Laravel-specific rules might lag. Mitigation: Audit the laravel preset’s rules against Laravel’s evolving syntax.

Key questions

• Preset customization:
  • Can the laravel preset be extended without duplication (e.g., adding custom rules while inheriting base Laravel-specific rules)?
  • Are there Laravel-specific rules (e.g., for php artisan output, migration files) that are not covered by the presets?
• Blade and Laravel-specific files:
  • Does the package handle .blade.php, .env, or composer.json files out of the box, or require additional rules?
  • How does it treat dynamic use statements (e.g., use App\Models\${model}) vs. static imports?
• CI/CD integration:
  • Are there recommended GitHub Actions/GitLab CI templates for this package?
  • Does it support incremental fixing (e.g., only fix changed files in PRs)?
• Backward compatibility:
  • What’s the deprecation policy for presets (e.g., will Php81 be removed after PHP 8.1 EOL)?
  • Are there breaking changes planned for Laravel-specific rules in future versions?

Integration Approach

Stack fit

• Laravel projects: Ideal for teams using Laravel 8.x+ with PHP 8.1–8.4, where the presets align with modern syntax (e.g., enums, readonly properties, match expressions).
• Multi-repo ecosystems: Reduces duplication in monorepos or multi-package setups (e.g., Spatie’s Laravel Package Generator) by centralizing config via Composer.
• CI/CD pipelines: Designed for pre-commit hooks (e.g., Laravel Pint integration) and CI checks (e.g., failing PRs on style violations).
• Developer tooling: Compatible with PHPStorm, VSCode (via extensions), and Laravel Forge for standardized local/remote environments.

Migration path

1. Pre-migration audit:
   • Run composer show php-cs-fixer to check current version.
   • Backup existing .php-cs-fixer.php or php-cs-fixer.dist.php.
   • Test with a subset of files:

     vendor/bin/php-cs-fixer fix app/Http/Controllers --config=vendor/beste/php-cs-fixer-config/laravel --dry-run
     

2. Installation:
   • Add to composer.json (dev dependency):

     "require-dev": {
         "beste/php-cs-fixer-config": "^3.3"
     }
     

   • Run composer update beste/php-cs-fixer-config --with-dependencies.
3. Configuration adoption:
   • New projects: Use the preset directly:

     // .php-cs-fixer.php
     <?php
     return Beste\PhpCsFixerConfig\Config::laravel();
     

   • Existing projects: Extend the base config:

     <?php
     return (new Beste\PhpCsFixerConfig\Config())
         ->setRules([
             '@PSR12' => true,
             'laravel:risky' => true,
             'line_ending' => true, // Override if needed
         ]);
     

4. CI/CD integration:
   • Add to GitHub Actions (.github/workflows/php-cs-fixer.yml):

     - name: PHP-CS-Fixer
       run: vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.php --allow-risky=yes --diff
     

   • For pre-commit hooks, use Laravel Pint or a custom script:

     composer require --dev laravel/pint
     ./vendor/bin/pint --test
     

5. Validation:
   • Run php-cs-fixer fix --dry-run on the full codebase.
   • Verify Blade templates and Laravel-specific files (e.g., migrations, Artisan commands) are formatted correctly.

Compatibility

• PHP versions: Supports PHP 8.1–8.4 (via Php81/Php82 presets). PHP 8.0 and below are not recommended (per changelog).
• Laravel versions: Tested with Laravel 8.x–10.x. Laravel 7.x may require manual rule adjustments.
• Tooling conflicts:
  • Laravel Pint: The package is complementary (Pint uses PHP-CS-Fixer under the hood). Prefer Pint for Laravel-specific rules if available.
  • PSR-12: The presets include @PSR12, but may override some rules (e.g., line_ending). Audit for conflicts.
• Custom rules: The package allows rule overrides, but ensure they don’t conflict with Laravel’s built-in tools (e.g., php artisan make:model).

Sequencing

1. Phase 1 (Pilot):
   • Adopt in one Laravel project (e.g., a non-critical module).
   • Test with laravel preset (avoid laravel-strict initially).
2. Phase 2 (Validation):
   • Run in CI for 2 weeks to catch false positives.
   • Gather feedback from developers on Blade/Artisan-specific issues.
3. Phase 3 (Rollout):
   • Standardize across all Laravel projects via Composer.
   • Update documentation and onboarding guides.
4. Phase 4 (Optimization):
   • Benchmark CI performance and adjust parallelism.
   • Consider custom presets for project-specific needs.

Operational Impact

Maintenance

• Low effort: The package is MIT-licensed and maintained by BESTE