Facile Coding Standard Laravel Package

Getting Started

Install the package with composer require --dev facile-it/facile-coding-standard. Upon installation, a Composer plugin prompts for project-specific configuration (e.g., source directories) and auto-generates .php-cs-fixer.dist.php with updated defaults for PHP 8.1–8.4 (PHP 7.4 and 8.0 are no longer supported). The config now includes PER-CS 3.0 rules by default, with new additions like multiline_promoted_properties and no_redundant_readonly_property. Run composer cs-check to lint code or composer cs-fix to auto-fix—no extra setup is needed for standard Laravel projects using PSR-4 autoloading.

Implementation Patterns

• CI/CD: Use composer cs-check as a non-blocking lint step in pre-commit hooks or GitHub Actions. For risky rules (e.g., @PER-CS3x0:risky), explicitly enable them via .php-cs-fixer.php:

  $config->setRules([
      '@PER-CS3x0:risky' => true,
      'no_useless_printf' => true,
  ]);
  

• IDE Integration: Configure PhpStorm/VS Code to run php-cs-fixer fix using the generated .php-cs-fixer.dist.php. Note that trailing commas now apply to all multi-line statements (not just arrays) due to PER-CS 3.0 alignment.
• Customizing Rules: Avoid editing .php-cs-fixer.dist.php directly. Use .php-cs-fixer.php to override defaults, e.g.:

  $config->setRiskyAllowed(true); // Enable risky rules globally
  $config->setUsingCache(false);  // Disable cache for monorepos
  

• Laravel Projects: The config auto-includes app/, database/, src/, and tests/ via Composer autoloader. Verify composer.json autoload sections are correct, as only psr-0, psr-4, and classmap are detected.
• Risky Rules: Enable cautiously via .php-cs-fixer.php using @PER-CS3x0:risky (replaces deprecated @PER-CS2.0:risky). New risky rules include no_useless_printf.

Gotchas and Tips

• PHP Version Drop: PHP 7.4 and 8.0 are no longer supported—ensure your project meets the 8.1+ requirement.
• Trailing Commas: PER-CS 3.0 now enforces trailing commas in all multi-line statements (e.g., if conditions, foreach), not just arrays. Test with composer cs-check --diff to preview changes.
• Autoload Scope: Only psr-0, psr-4, and classmap are detected; files or exclude are ignored. If files aren’t linted, verify composer.json autoload settings.
• Cache Issues: Disable caching in monorepos with $config->setUsingCache(false) in .php-cs-fixer.php.
• Deprecated Rules: The package auto-updates deprecated rules (e.g., @PER-CS2.0:risky → @PER-CS3x0:risky), but always check CI logs after upgrades.
• Regenerate Config Safely: Use composer facile-cs-create-config --no-risky to reset configs after version bumps, excluding risky rules by default.
• Debugging Rules: Run php-cs-fixer fix --dry-run --diff -vvv to trace rule behavior, especially for edge cases like promoted properties or docblock normalization.
• New Rules: Test new defaults (multiline_promoted_properties, no_whitespace_in_empty_array) in a staging environment before enforcing them in CI.