Php Cs Fixer Custom Fixers Laravel Package

Getting Started

Minimal Setup

1. Install the package in your Laravel project:

   composer require --dev kubawerlos/php-cs-fixer-custom-fixers
   

2. Update your .php-cs-fixer.dist.php to register the custom fixers:

   <?php
   return (new PhpCsFixer\Config())
       ->registerCustomFixers(new \PhpCsFixerCustomFixers\Fixers())
       ->setRules([
           '@PSR2' => true,
           // Add your custom fixers here
           \PhpCsFixerCustomFixers\Fixer\NoLeadingSlashInGlobalNamespaceFixer::name() => true,
       ]);
   

3. Run PHP CS Fixer to apply changes:

   vendor/bin/php-cs-fixer fix
   

First Use Case

Fix global namespace slashes (e.g., \Foo → Foo):

-$x = new \Foo();
+$x = new Foo();

Run:

vendor/bin/php-cs-fixer fix --rules=NoLeadingSlashInGlobalNamespaceFixer

Implementation Patterns

Workflow Integration

1. Laravel CI/CD Pipeline:

   • Add a step to run PHP CS Fixer with custom fixers in your GitHub Actions/GitLab CI:

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

   • Fail the build if changes are detected (enforce consistency).

2. Pre-Commit Hook:

   • Use php-cs-fixer with husky or pre-commit to auto-fix files before commit:

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

3. Team Onboarding:

   • Document the custom fixers in your team’s coding standards doc (e.g., CONTRIBUTING.md).
   • Example:

     "Use NoLeadingSlashInGlobalNamespaceFixer to avoid slashes in global namespace classes."

Common Patterns

• Group Related Fixers: Combine fixers for similar concerns (e.g., PHPDoc, PHPUnit, or performance):

  ->setRules([
      // PHPDoc fixers
      \PhpCsFixerCustomFixers\Fixer\PhpdocNoSuperfluousParamFixer::name() => true,
      \PhpCsFixerCustomFixers\Fixer\PhpDocPropertySorterFixer::name() => true,
      // PHPUnit fixers
      \PhpCsFixerCustomFixers\Fixer\PhpUnitAssertArgumentsOrderFixer::name() => true,
  ]);
  

• Conditional Fixers: Use fixers selectively based on project needs (e.g., disable NoNullableBooleanTypeFixer for legacy code):

  ->setRules([
      \PhpCsFixerCustomFixers\Fixer\NoNullableBooleanTypeFixer::name() => [
          'risky' => false, // Skip if null checks are critical
      ],
  ]);
  

• Custom Config for Teams: Share a base config (e.g., php-cs-fixer-team.php) and allow overrides:

  // php-cs-fixer-team.php
  return (new PhpCsFixer\Config())
      ->registerCustomFixers(new \PhpCsFixerCustomFixers\Fixers())
      ->setRules([
          '@PSR12' => true,
          \PhpCsFixerCustomFixers\Fixer\NoCommentedOutCodeFixer::name() => true,
      ]);
  

Gotchas and Tips

Pitfalls

1. Bootstrap Requirement:

   • If using php-cs-fixer/shim, manually require the bootstrap:

     require __DIR__ . '/vendor/kubawerlos/php-cs-fixer-custom-fixers/bootstrap.php';
     

   • Symptom: Fixers fail silently or throw ClassNotFound errors.

2. Risky Fixers:

   • Some fixers (e.g., IssetToArrayKeyExistsFixer, NoNullableBooleanTypeFixer) may break logic.
   • Mitigation: Test in a staging environment or disable risky fixers:

     \PhpCsFixerCustomFixers\Fixer\IssetToArrayKeyExistsFixer::name() => [
         'risky' => false,
     ],
     

3. Deprecated Fixers:

   • Some fixers (e.g., DataProviderNameFixer) are deprecated in favor of PHP CS Fixer’s built-ins.
   • Tip: Replace with native rules (e.g., php_unit_data_provider_name) to avoid future conflicts.

4. Performance Impact:

   • Fixers like NoDuplicatedArrayKeyFixer or NoDuplicatedImportsFixer can slow down large codebases.
   • Tip: Run on specific files/directories:

     vendor/bin/php-cs-fixer fix app/Http/Controllers/
     

Debugging Tips

• Dry Run: Always use --diff or --dry-run first to preview changes:

  vendor/bin/php-cs-fixer fix --diff
  

• Fix Specific Files: Target problematic files directly:

  vendor/bin/php-cs-fixer fix app/Models/User.php --rules=NoUselessCommentFixer
  

• Ignore Files: Exclude files/directories from fixing:

  ->setFinder(
      PhpCsFixer\Finder::create()
          ->exclude('vendor')
          ->exclude('storage')
  )
  

Extension Points

1. Custom Fixer Logic:

   • Extend the package by creating your own fixers (e.g., for Laravel-specific patterns):

     class LaravelRouteNameFixer extends AbstractFixer
     {
         public function getName(): string { return 'laravel_route_name'; }
         // Implement fix logic...
     }
     

   • Register it alongside the existing fixers:

     ->registerCustomFixers(new \PhpCsFixerCustomFixers\Fixers())
     ->registerCustomFixers(new \App\Fixers\LaravelFixers())
     

2. Override Default Config:

   • Modify fixer configurations globally (e.g., adjust CommentedOutFunctionFixer to allow dd()):

     \PhpCsFixerCustomFixers\Fixer\CommentedOutFunctionFixer::name() => [
         'functions' => ['print_r', 'var_dump'], // Exclude 'dd'
     ],
     

3. Combine with Other Tools:

   • Use with psalm or phpstan to catch logical errors before applying fixers.
   • Example workflow:

     composer test:static
     vendor/bin/php-cs-fixer fix
     

Pro Tips

• Laravel-Specific Fixers: Add fixers for Laravel idioms (e.g., Route::name() formatting):

  \PhpCsFixerCustomFixers\Fixer\NoUselessStrlenFixer::name() => true,
  // Custom: Ensure Route names use snake_case
  

• Version Pinning: Pin the package version in composer.json to avoid unexpected updates:

  "require-dev": {
      "kubawerlos/php-cs-fixer-custom-fixers": "^1.0"
  }
  

• CI Feedback: Use GitHub’s php-cs-fixer action to enforce standards:

  - name: PHP CS Fixer
    uses: docker://oskarstark/php-cs-fixer-ga
    with:
      args: "--diff --dry-run"