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), then auto-generates .php-cs-fixer.dist.php and adds cs-check/cs-fix scripts to composer.json. The default config targets PSR-12 + PER-CS 3.0 rules with sensible defaults for PHP 7.4–8.4, including modernizing rules (e.g., assign_null_coalescing_to_coalesce_equal, backtick_to_shell_exec). Run composer cs-check to lint code or composer cs-fix to auto-fix — no extra setup 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 (e.g., php-cs-fixer fix --dry-run).
• IDE Integration: Configure PhpStorm/VS Code to run php-cs-fixer fix via external tools using the generated .php-cs-fixer.dist.php.
• Customizing Rules: Avoid editing .php-cs-fixer.dist.php directly. Instead, create .php-cs-fixer.php to override config (e.g., setUsingCache(false)) or extend rule sets via CompositeRulesProvider.
• Laravel Projects: The config auto-includes app/, database/, src/, and tests/ via Composer autoloader definitions — verify composer.json autoload sections are correct.
• Risky Rules: Enable cautiously via .php-cs-fixer.php using RiskyRulesProvider (e.g., for null_coalesce_equal_operator or yield_from).

Gotchas and Tips

• Autoload Scope: Only psr-0, psr-4, and classmap are detected; files or exclude are ignored — if files aren’t linted, check composer.json autoload settings.
• Cache Issues: The default cache path may conflict in monorepos — disable with $config->setUsingCache(false) in .php-cs-fixer.php.
• Deprecated Rules: The package auto-replaces deprecated rules (e.g., return_type_declaration → PER-CS), but always check CI logs after upgrades to PHP-CS-Fixer.
• Plugin Conflicts: Ensure no other CS tools (e.g., squizlabs/php_codesniffer) conflict — this package only integrates with PHP-CS-Fixer.
• Regenerate Config Safely: Use composer facile-cs-create-config (not manual edits) to reset configs after version bumps — supports --no-risky and --no-dev flags.
• Debugging Rules: Run php-cs-fixer fix --dry-run --diff -vvv to trace rule behavior — useful for tricky edge cases like trait ordering or docblock normalization.