Php Cs Fixer Config Laravel Package

Technical Evaluation

Architecture Fit

• Pros:

  • PSR-12 Alignment: Ensures consistency with modern PHP/Laravel standards, reducing cognitive load for developers.
  • PHP 8.4 Support: Future-proofs the codebase for Laravel 10+ and newer PHP versions.
  • Extensibility: Inheritance-based customization allows TPMs to adapt rules for team-specific needs (e.g., legacy Laravel 8 codebases).
  • Cache Optimization: Reduces CI/CD overhead with .php-cs-fixer.cache, improving pipeline performance.
  • Git Integration: Explicit .gitignore rules prevent cache pollution, keeping repositories clean.

• Cons:

  • Laravel-Specific Gaps: Lacks built-in rules for Laravel conventions (e.g., use App\ ordering, facade imports). Requires manual overrides.
  • Risky Rules by Default: Rules like native_function_invocation or declare_strict_types may break legacy code unless explicitly configured.
  • PHP-CS-Fixer Dependency: Tight coupling to PHP-CS-Fixer v3.57+ introduces upgrade risks if the config isn’t maintained.
  • No IDE Plugin: Relies on CLI/editor plugins (e.g., PHPStorm’s built-in formatter) for real-time feedback, adding friction for some teams.

Integration Feasibility

• Low-Effort Setup: Requires only:
  • Composer install (composer require --dev m6web/php-cs-fixer-config).
  • Minimal config file (.php-cs-fixer.dist.php) with path adjustments for src//tests/.
  • Optional: Makefile for CI/CD integration (3 commands: cs, cs-fix, cs-ci).
• Tooling Agnostic: Works with:
  • CI/CD: GitHub Actions, GitLab CI, CircleCI (via php-cs-fixer CLI).
  • Pre-commit Hooks: Husky, pre-commit frameworks.
  • CI Pipelines: Can gate merges or run as a post-build step.
• Backward Compatibility: Drops PHP 7.4 support (aligned with Laravel’s PHP 8.1+ requirement), reducing maintenance burden.

Technical Risk

Key Questions for TPM

1. Adoption Readiness:
   • Does the team already use PHP-CS-Fixer? If not, what’s the onboarding plan (e.g., training, documentation)?
   • Are developers familiar with PSR-12, or will this introduce resistance?
2. Customization Needs:
   • Should Laravel-specific rules (e.g., ordered_imports, no_unused_imports) be added to the base config?
   • Are there legacy code exceptions (e.g., PHP 7.4, Laravel < 8) that need whitelisting?
3. CI/CD Strategy:
   • Should failures block merges (e.g., GitHub Actions if: always()), or be warnings?
   • How will this integrate with existing linters (e.g., Psalm, PHPStan)? Will it run in parallel or sequentially?
4. Maintenance:
   • Who will update the config if PHP-CS-Fixer rules change (e.g., new PSR-12 additions)?
   • Should the package version be locked to ^5.1 or ~5.1.0 in composer.json?
5. Tooling Synergy:
   • Will this replace or complement existing tools (e.g., Pint, Laravel’s built-in artisan format)?
   • Should it integrate with Laravel Forge or Envoyer for deployment-time checks?

Integration Approach

Stack Fit

• Laravel Ecosystem:
  • PHP 8.4+: Fully compatible with Laravel 10+ and modern PHP features (e.g., native_function_invocation, declare_strict_types).
  • PSR-4 Autoloading: Works seamlessly with Laravel’s composer.json structure.
  • Artisan Integration: Can be wrapped in a custom Artisan command (e.g., php artisan cs:fix) for Laravel-native workflows.
• Tooling Synergy:
  • CI/CD: Plugs into GitHub Actions, GitLab CI, or CircleCI via php-cs-fixer CLI.

    # Example GitHub Actions workflow
    jobs:
      cs-check:
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v4
          - run: composer install
          - run: make cs-ci  # Uses the provided Makefile target
    

  • Pre-commit Hooks: Integrates with Husky or pre-commit frameworks:

    # .husky/pre-commit
    

  #!/bin/sh make cs # Blocks commits with violations

  - **IDE Support**: Configure PHPStorm/VSCode to use the config file for real-time fixes:
  - **PHPStorm**: Set `.php-cs-fixer.dist.php` in `Settings > PHP > Code Sniffer`.
  - **VSCode**: Use the `PHP CS Fixer` extension with the config path.
  

• Laravel-Specific Extensions:
  • Add Laravel conventions to the config:

    $rules = (new M6Web\CS\Config\BedrockStreaming())->getRules();
    $rules['ordered_imports'] = true;
    $rules['no_unused_imports'] = true;
    $rules['single_blank_line_before_namespace'] = true;
    return $rules;
    

Migration Path

1. Phase 1: Assessment (1–2 Days)

   • Install the package:

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

   • Generate the config file:

     cp vendor/m6web/php-cs-fixer-config/.php-cs-fixer.dist.php.example .php-cs-fixer.dist.php
     

   • Run a dry analysis:

     make cs  # Checks for violations without fixing
     

   • Review violations in the team. Document exceptions (e.g., legacy code).

2. Phase 2: Customization (2–5 Days)

   • Extend the config for Laravel-specific rules (see Stack Fit above).
   • Override risky rules if needed:

     $rules = (new M6Web\CS\Config\BedrockStreaming())->getRules();
     $rules['risky_allowed'] = false;  // Disable risky rules by default
     $rules['native_function_invocation'] = ['scope' => 'namespaced'];  // Customize scope
     

   • Test with a subset of the codebase:

     make cs-fix --path=src/App/Http/Controllers
     

3. Phase 3: CI/CD Integration (1–3 Days)

   • Add the cs-ci target to your CI pipeline (see Stack Fit for examples).
   • Configure failure behavior:
     • Strict: Block merges on violations (recommended for new projects).
     • Lenient: Log warnings but allow merges (for legacy codebases).
   • Example GitHub Actions:

     - name: PHP CS Fixer
       run: make cs-ci
       if: always()  # Run even if tests fail
     

4. Phase 4: Developer Onboarding (Ongoing)

   • Add a Makefile to the project template:

     cs: ./vendor/bin/php-cs-fixer fix --dry-run --diff
     cs-fix: ./vendor/bin/php-cs-fixer fix
     cs-ci: ./vendor/bin/php-cs-fixer fix --dry-run --using-cache=no --verbose
     

   • Document the workflow in CONTRIBUTING.md:

     ## Code Style
     Ensure your changes pass PHP CS Fixer:
     ```bash
     make cs  # Check for violations
     make cs-fix  # Auto-fix violations
     

   • Train developers on:
     • Running make cs locally before commits.
     • Customizing rules via the config file.

Compatibility

• Laravel Versions:
  • Laravel 10+: Full support (PHP 8.4+).
  • Laravel 9: Partial support (PHP 8.1–