Php Cs Fixer Extensions Laravel Package

Getting Started

1. Installation: Add the package to your project via Composer:

   composer require --dev slam/php-cs-fixer-extensions
   

2. Configure: Create or update your .php_cs file in the project root. Start with the basic example from the README and adjust paths/rules as needed:

   <?php
   $config = new PhpCsFixer\Config();
   $config->setRiskyAllowed(true);
   
   $config->registerCustomFixers([
       new SlamCsFixer\FinalAbstractPublicFixer(),
       new SlamCsFixer\FinalInternalClassFixer(),
       new SlamCsFixer\FunctionReferenceSpaceFixer(),
       new SlamCsFixer\InlineCommentSpacerFixer(),
       new SlamCsFixer\PhpFileOnlyProxyFixer(new PhpCsFixer\Fixer\Basic\BracesFixer()),
       new SlamCsFixer\Utf8Fixer(),
   ]);
   
   $config->setRules([
       'Slam/final_abstract_public' => true,
       'Slam/final_internal_class' => true,
       'Slam/function_reference_space' => true,
       'Slam/inline_comment_spacer' => true,
       'Slam/php_only_braces' => true,
       'Slam/utf8' => true,
   ]);
   
   $config->getFinder()
       ->in(__DIR__ . '/app')
       ->in(__DIR__ . '/tests')
       ->name('*.php')
       ->name('*.phtml');
   
   return $config;
   

3. First Use Case: Run PHP-CS-Fixer to auto-fix your codebase:

   vendor/bin/php-cs-fixer fix
   

   Focus on the Utf8Fixer and final_abstract_public rules first, as they address common Laravel pain points (encoding issues and abstract class misuse).

Implementation Patterns

Workflow Integration

1. CI/CD Pipeline: Add a step to run PHP-CS-Fixer with this extension in your CI (e.g., GitHub Actions):

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

   Use --diff to show changes and --dry-run to fail if fixes are needed.

2. Pre-Commit Hooks: Use tools like Husky or Laravel Pint to run PHP-CS-Fixer locally:

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

3. Team Onboarding:

   • Document the new rules in your CONTRIBUTING.md.
   • Create a php-cs-fixer section in your team’s style guide with examples of fixed vs. non-compliant code.

Rule-Specific Patterns

Laravel-Specific Tips

1. Blade/PHTML Files: Use the PhpFileOnlyProxyFixer to apply braces rules to *.php files while excluding Blade templates:

   $config->registerCustomFixers([
       new SlamCsFixer\PhpFileOnlyProxyFixer(new PhpCsFixer\Fixer\Basic\BracesFixer()),
   ]);
   

2. Doctrine Entities: Exclude Doctrine entities from final_internal_class if they use attributes (e.g., @ORM\Entity):

   $config->getFinder()
       ->exclude('app/Entities');
   

3. PHPUnit Tests: Add test directories to the finder:

   $config->getFinder()
       ->in(__DIR__ . '/tests/Unit')
       ->in(__DIR__ . '/tests/Feature');
   

Gotchas and Tips

Pitfalls

1. setRiskyAllowed(true):

   • Enabling risky rules can modify abstract classes, breaking inheritance hierarchies.
   • Fix: Test on a branch first or disable individual risky rules:

     $config->setRules([
         'Slam/final_abstract_public' => false, // Disable if risky
     ]);
     

2. UTF-8 Encoding Issues:

   • The Utf8Fixer may fail on files with mixed encodings (e.g., UTF-8 BOM or ISO-8859-1).
   • Fix: Exclude problematic files or pre-process them with iconv:

     iconv -f ISO-8859-1 -t UTF-8 file.php > temp && mv temp file.php
     

3. Doctrine Attribute Conflicts:

   • FinalInternalClassFixer may flag Doctrine entities with @ORM\* attributes as "internal."
   • Fix: Exclude Doctrine directories or update the fixer’s logic (see PR #18).

4. PHP 8.5+ Features:

   • Some fixers (e.g., readonly class support) may not work on older PHP versions.
   • Fix: Use php-cs-fixer’s --version flag to check compatibility:

     vendor/bin/php-cs-fixer --version
     

Debugging Tips

1. Dry Runs: Always use --dry-run to preview changes:

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

2. Rule-Specific Debugging:

   • Isolate rules to identify culprits:

     vendor/bin/php-cs-fixer fix --rules=Slam/utf8 --dry-run
     

   • Use --verbose for detailed output:

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

3. Custom Fixers:

   • Extend existing fixers for project-specific needs. Example: Override FinalAbstractPublicFixer to exclude certain classes:

     class CustomFinalAbstractPublicFixer extends SlamCsFixer\FinalAbstractPublicFixer {
         protected function isRisky(): bool {
             return false; // Disable risky behavior
         }
     }
     

Configuration Quirks

1. Finder Exclusions:

   • Use ->exclude() to skip directories (e.g., vendor/, node_modules/):

     $config->getFinder()->exclude('vendor');
     

2. Rule Priorities:

   • Order matters! Run Utf8Fixer before other rules to avoid encoding-related errors:

     $config->setRules([
         'Slam/utf8' => true,
         'Slam/final_abstract_public' => true,
     ]);
     

3. Caching:

   • Enable PHP-CS-Fixer’s cache for faster runs (but disable in CI to ensure fresh checks):

     $config->setCacheFile(__DIR__ . '/.php_cs_fixer.cache');
     

Extension Points

1. Custom Fixers:

   • Create your own fixers by extending SlamCsFixer\AbstractFixer. Example:

     namespace App\CsFixer;
     
     use PhpCsFixer\Fixer\FixerInterface;
     use PhpCsFixer\Tokenizer\Tokens;
     
     class LaravelUseStatementFixer implements FixerInterface {
         public function isRisky(): bool { return false; }
         public function getName() { return 'Laravel_use_statement'; }
         public function getDescription() { return 'Fix Laravel-specific use statements'; }
         public function fix(Tokens $tokens) { /* ... */ }
     }
     

2. Rule Sets:

   • Combine rules into reusable sets for different contexts (e.g., laravel, tests):

     $config->importRulesFromFile(__DIR__ . '/rules/laravel.php');
     

3. CI/CD Integration:

   • Fail builds if PHP-CS