Facile Coding Standard Laravel Package

Getting Started

Minimal Steps to Begin

1. Installation:

   composer require --dev facile-it/facile-coding-standard
   

   The installer will automatically generate:

   • .php-cs-fixer.dist.php (default config)
   • composer.json scripts (cs-check, cs-fix)

2. First Use Case: Run a dry check to preview changes:

   composer cs-check
   

   Apply fixes automatically:

   composer cs-fix
   

3. Key Files:

   • .php-cs-fixer.dist.php: Default config (edit via .php-cs-fixer.php for overrides).
   • composer.json: Contains cs-check/cs-fix scripts.

Implementation Patterns

Daily Workflows

1. Pre-Commit Hooks: Integrate with php-cs-fixer via Git hooks (e.g., pre-commit) to enforce standards before commits:

   composer cs-check  # Fails if violations exist
   

2. CI/CD Pipeline: Add to Laravel’s CI (e.g., GitHub Actions) to block non-compliant PRs:

   - name: Run Facile Coding Standard
     run: composer cs-check
   

3. Team Onboarding:

   • Document the cs-fix command in your CONTRIBUTING.md.
   • Use composer facile-cs-create-config to regenerate config if rules update.

4. Partial Fixes: Target specific files/directories:

   php-cs-fixer fix app/Http/Controllers --dry-run
   

5. Risky Rules: Enable risky rules (e.g., class_keyword) via a custom config:

   $config = include __DIR__ . '/.php-cs-fixer.dist.php';
   $config->setRules([
       '@PER-CS3x0:risky' => true,
       'class_keyword' => true,
   ]);
   

Integration Tips

1. Laravel-Specific:

   • Exclude vendor/ and storage/ from autoload paths in .php-cs-fixer.dist.php:

     $finder->exclude(['vendor', 'storage']);
     

   • Add bootstrap/cache/ to exclude:

     $finder->ignoreDotFiles(true)->ignoreVCS(true);
     

2. Custom Rules: Extend the CompositeRulesProvider to add project-specific rules:

   $rulesProvider = new Facile\CodingStandards\Rules\CompositeRulesProvider([
       new Facile\CodingStandards\Rules\DefaultRulesProvider(),
       new Facile\CodingStandards\Rules\ArrayRulesProvider([
           'array_push' => true,
           'no_whitespace_in_empty_array' => true,
       ]),
   ]);
   

3. Symfony/Laravel Compatibility:

   • Use --no-risky flag with facile-cs-create-config to avoid Symfony-specific rules:

     composer facile-cs-create-config --no-risky
     

4. PHPStorm Integration:

   • Configure PHPStorm to use php-cs-fixer via: Settings > Editor > Code Style > PHP > PHP-CS-Fixer.
   • Point to your .php-cs-fixer.dist.php.

Gotchas and Tips

Pitfalls

1. Risky Rules:

   • Rules like class_keyword or long_to_shorthand_operator may break existing code.
   • Fix: Test risky rules in a staging environment first.

2. PHP Version Mismatches:

   • The package drops support for PHP 7.4/8.0 in v1.5.0.
   • Fix: Update your php-cs-fixer version and PHP runtime:

     composer require php-cs-fixer:^3.88
     

3. Autoload Paths:

   • The installer assumes psr-4, psr-0, or classmap. Custom autoloads (e.g., files) may be missed.
   • Fix: Manually add paths to $finder in .php-cs-fixer.dist.php:

     $finder->in(__DIR__ . '/custom-path');
     

4. Caching Issues:

   • Disabling cache ($config->setUsingCache(false)) may slow down checks but ensures up-to-date rules.
   • Tip: Rebuild cache after major updates:

     composer facile-cs-create-config
     

5. Heredoc Rules:

   • Rules like heredoc_to_nowdoc or multiline_string_to_heredoc are marked "to be discussed" and may change behavior.
   • Tip: Exclude them temporarily if they cause false positives:

     $config->setRules([
         'heredoc_to_nowdoc' => false,
     ]);
     

Debugging Tips

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

   composer cs-check -- --dry-run --diff
   

2. Verbose Output: Enable debug mode for detailed rule explanations:

   php-cs-fixer fix --verbose
   

3. Rule-Specific Fixes: Target a single rule to debug:

   php-cs-fixer fix --rules=phpdoc_summary
   

4. Config Validation: Validate your .php-cs-fixer.php for syntax errors:

   php -l .php-cs-fixer.php
   

Extension Points

1. Custom Rulesets: Create a project-specific ruleset by extending CompositeRulesProvider:

   class AppRulesProvider extends Facile\CodingStandards\Rules\CompositeRulesProvider {
       public function __construct() {
           parent::__construct([
               new Facile\CodingStandards\Rules\DefaultRulesProvider(),
               new Facile\CodingStandards\Rules\ArrayRulesProvider([
                   'no_whitespace_in_empty_array' => true,
                   'array_push' => false, // Disable for legacy code
               ]),
           ]);
       }
   }
   

2. Rector Integration: Use Rector (added in v1.5.0) for refactoring alongside CS fixes:

   composer require --dev rector/rector
   

   Configure in rector.php:

   return static function (RectorConfig $config): void {
       $config->paths([__DIR__ . '/src']);
       $config->rules([
           new SetTypeToCast(),
           new TernaryToElvisOperator(),
       ]);
   };
   

3. GitHub Actions: Cache php-cs-fixer between runs to speed up CI:

   - name: Cache PHP-CS-Fixer
     uses: actions/cache@v3
     with:
       path: ~/.cache/php-cs-fixer
       key: ${{ runner.os }}-php-cs-fixer
   

4. IDE Shortcuts: Bind composer cs-fix to a keyboard shortcut in PHPStorm for quick fixes:

   • Settings > Keymap > Other > Run External Tool.
   • Map to composer cs-fix.