Php Cs Fixer Custom Fixers Laravel Package

Technical Evaluation

Architecture Fit

• Low Coupling: The package extends PHP CS Fixer’s existing ecosystem without modifying core Laravel/PHP frameworks. It integrates as a plugin, aligning with Laravel’s modular design (e.g., php-cs-fixer is already a dev dependency in many Laravel projects).
• Non-Invasive: Fixers target code style (not logic), making them ideal for CI/CD pipelines or pre-commit hooks. No runtime impact on application behavior.
• Complementary: Fills gaps in PHP CS Fixer’s built-in rules (e.g., NoLeadingSlashInGlobalNamespaceFixer, PhpdocNoSuperfluousParamFixer), addressing niche Laravel-specific patterns (e.g., Doctrine migrations, PhpStorm-generated comments).

Integration Feasibility

• Composer-Based: Zero build steps required—install via composer require --dev. Works seamlessly with Laravel’s dependency management.
• Configuration-Driven: Minimal setup (register fixers in php-cs-fixer.config.php), leveraging Laravel’s existing php-cs-fixer integration (e.g., via laravel-pint or custom scripts).
• Toolchain Synergy: Compatible with:
  • Laravel Pint (if using pint instead of php-cs-fixer directly).
  • GitHub Actions/GitLab CI: Can be added to existing linting pipelines (e.g., php-cs-fixer fix --diff).
  • Pre-Commit Hooks: Via php-cs-fixer’s --dry-run or pre-commit integration.

Technical Risk

Key Questions for TPM

1. Adoption Scope:

   • Should this replace existing php-cs-fixer rules or supplement them? (E.g., enable NoUselessCommentFixer but keep @PSR12 rules.)
   • Which fixers align with the team’s coding standards? (Prioritize low-risk, high-impact fixers like NoTrailingCommaInSinglelineFixer.)

2. CI/CD Impact:

   • How will this integrate with existing linting? (Example: Add to php-cs-fixer step in GitHub Actions.)
   • Should it block merges (--fix --allow-risky) or run as a warning (--dry-run)?

3. Developer Experience:

   • Will the team need training on new rules? (E.g., ForeachUseValueFixer may surprise developers.)
   • Should IDE hints (e.g., PHPStorm) be configured to recognize these fixers?

4. Legacy Code:

   • Are there exemptions for older codebases? (Use ignore rules in config.)
   • How will Doctrine/PhpStorm-generated comments be handled? (E.g., NoDoctrineMigrationsGeneratedCommentFixer may need selective disabling.)

5. Testing:

   • Should a baseline commit be created to measure impact? (Run php-cs-fixer fix --diff on main.)
   • Are there unit tests for Laravel-specific edge cases? (E.g., Blade templates with foreach loops.)

Integration Approach

Stack Fit

• Laravel Ecosystem:

  • Native Support: Works with Laravel’s default php-cs-fixer setup (no framework modifications needed).
  • Pint Integration: If using laravel/pint, configure it to use the custom fixers via pint.yaml:

    finder:
      exclude: ["vendor"]
    fixer_custom_fixers: ["kubawerlos/php-cs-fixer-custom-fixers"]
    

  • Artisan Commands: Extend Laravel’s php-cs-fixer command or create a custom one (e.g., php artisan cs-fix:custom).

• Tooling Compatibility:

  • Pre-Commit: Add to .pre-commit-config.yaml:

    - repo: local
      hooks:
        - id: php-cs-fixer-custom
          name: PHP CS Fixer (Custom)
          entry: vendor/bin/php-cs-fixer fix --rules=@CustomRules --allow-risky
          language: system
    

  • VSCode/PHPStorm: Configure as an external tool with --diff for real-time feedback.

Migration Path

1. Phase 1: Audit

   • Run php-cs-fixer fix --dry-run --rules=@CustomRules on a feature branch to identify changes.
   • Exclude risky fixers (e.g., NoReferenceInFunctionDefinitionFixer) initially.

2. Phase 2: Incremental Adoption

   • Start with low-risk fixers (e.g., NoTrailingCommaInSinglelineFixer, NoUselessCommentFixer).
   • Gradually enable medium-risk fixers (e.g., ForeachUseValueFixer) with team buy-in.
   • Avoid high-risk fixers (e.g., NoNullableBooleanTypeFixer) unless critical.

3. Phase 3: CI Enforcement

   • Add to CI pipeline with --fix (auto-correct) or --diff (fail on changes).
   • Example GitHub Actions step:

     - name: PHP CS Fixer (Custom)
       run: vendor/bin/php-cs-fixer fix --rules=@CustomRules --allow-risky --diff
     

Compatibility

• PHP CS Fixer Version: Requires PHP CS Fixer v3.0+ (check Laravel’s default version).
• Laravel-Specific Quirks:
  • Blade Templates: Some fixers (e.g., ForeachUseValueFixer) may conflict with Blade syntax. Test on .blade.php files.
  • Doctrine Entities: NoDoctrineMigrationsGeneratedCommentFixer may need exclusion for database/migrations/.
• IDE Support: Ensure PHPStorm/VSCode’s PHP CS Fixer plugin is updated to recognize custom fixers.

Sequencing

Operational Impact

Maintenance

• Configuration Drift: Centralize rules in php-cs-fixer.config.php to avoid per-developer inconsistencies.
• Deprecation Handling: Monitor for deprecated fixers (e.g., DataProviderNameFixer) and migrate to native PHP CS Fixer rules.
• Update Cadence: Check for new releases quarterly (package is actively maintained).

Support

• Developer Training:
  • Create a cheat sheet for custom fixers (e.g., "Why NoLeadingSlashInGlobalNamespaceFixer matters").
  • Host a lunch-and-learn to demo the tool and address concerns.
• Troubleshooting:
  • Common issues:
    • Fixers misfiring on Blade templates (exclude .blade.php).
    • Performance slowdowns (parallelize with --parallel).
  • Provide a support channel (e.g., Slack thread) for questions.

Scaling

• Performance:
  • Parallel Processing: Use --parallel for large codebases (e.g., --parallel=8).