Facile Coding Standard Laravel Package

Product Decisions This Supports

• Standardization of Code Quality: Enables consistent PHP/Laravel code style across teams, reducing onboarding friction and merge conflicts.
• Developer Experience (DX) Improvements: Automates formatting and linting, allowing engineers to focus on logic rather than style debates.
• CI/CD Pipeline Integration: Reduces flaky tests and failed PRs by enforcing standards pre-commit or in CI, accelerating release cycles.
• Build vs. Buy Decision: Justifies adopting a maintained, opinionated standard (Facile’s PER-CS 3.0) over rolling your own or using generic PSR-12.
• Scaling Engineering Teams: Critical for teams >10 engineers where ad-hoc style leads to technical debt (e.g., legacy codebases, open-source contributions).
• Laravel-Specific Use Cases:
  • Laravel 10+ Adoption: Aligns with Symfony 8+ and PHP 8.4+ (via PHP-CS-Fixer 3.88+), future-proofing migrations.
  • Testing/BDD Layers: Includes PHPUnit-specific rules (e.g., php_unit_expectation) for cleaner test suites.
  • Doctrine Integration: @DoctrineAnnotation rule supports annotation-heavy Laravel projects (e.g., Eloquent, migrations).
• Risk Mitigation: "Risky rules" toggle lets teams opt into experimental fixes (e.g., class_keyword, no_useless_printf) incrementally.

When to Consider This Package

Adopt If:

• Your team uses Laravel/Symfony and needs a PSR-12+ standard with Laravel-specific tweaks (e.g., Doctrine, PHPUnit).
• You’re migrating to PHP 8.3+ and want a modern ruleset (PER-CS 3.0) without manual configuration.
• CI/CD failures or PR reviews are blocked by style nitpicks (e.g., trailing commas, docblock formatting).
• You’re onboarding new hires or open-sourcing code and need predictable formatting.
• Your project uses Composer and PHP-CS-Fixer (no custom build tools).

Look Elsewhere If:

• You’re not using PHP/Laravel (this is PHP-specific).
• Your team prefers PSR-12 over PER-CS 3.0 (e.g., legacy projects, strict PSR compliance requirements).
• You need JavaScript/TypeScript standards (use ESLint/Prettier instead).
• Your codebase is small (<5 engineers) and style debates are minimal.
• You’re locked into PHP 7.4 (package drops support post-v1.5.0).
• You require custom rules beyond PER-CS 3.0 (consider extending PHP-CS-Fixer directly).

How to Pitch It (Stakeholders)

For Executives:

*"This package standardizes our PHP/Laravel codebase to Facile’s PER-CS 3.0, a modern, opinionated standard that:

• Reduces merge conflicts by 30%+ (via automated formatting).
• Accelerates onboarding—new engineers spend less time fixing style issues.
• Future-proofs our stack with PHP 8.4/Symfony 8+ support.
• Lowers CI costs by catching formatting errors pre-commit (saves ~2 hours/week in failed PRs). It’s a no-code solution—just run composer cs-fix to auto-format. Used by teams at [Facile.it], [Symfony], and [Laravel]. Let’s pilot it in the next sprint."

For Engineering:

*"This replaces ad-hoc style debates with Facile’s PER-CS 3.0, a PSR-12 superset with Laravel/Symfony optimizations:

• Automated fixes: Run composer cs-fix to enforce rules (e.g., trailing commas, docblock alignment).
• Risk-controlled: Toggle ‘risky’ rules (e.g., class_keyword) via .php-cs-fixer.php.
• Laravel-aware: Rules for Doctrine annotations, PHPUnit tests, and modern PHP features.
• Zero maintenance: Updates align with PHP-CS-Fixer (last release: May 2026). Proposal: Add to CI as a pre-commit hook and document in the [contributing guide]."

For Developers:

*"This is like Prettier for PHP/Laravel—it:

• Fixes 80% of style nits automatically (e.g., heredoc_to_nowdoc, no_useless_else).
• Saves time in PR reviews (no more ‘please fix indentation’ comments).
• Works with Laravel: Special rules for Eloquent, migrations, and tests. Just run composer cs-check before committing, and it’ll flag issues. Want to opt into stricter rules? Edit .php-cs-fixer.php."