Coding Standard Laravel Package

Technical Evaluation

Architecture Fit

• Low architectural impact: This package is a PHP Coding Standard (PSR-12 compliant) enforcer, leveraging php-cs-fixer under the hood. It does not modify core Laravel functionality but enforces consistency in code style.
• Complementary to Laravel: Aligns with Laravel’s existing PSR standards (PSR-1, PSR-2, PSR-4) and integrates seamlessly with tools like php-cs-fixer already used in Laravel projects.
• Non-intrusive: Operates at the tooling layer, not the framework layer, making it easy to adopt without architectural refactoring.

Integration Feasibility

• High feasibility: Requires minimal setup—just a .php_cs.dist config file and a composer require command.
• Leverages existing tools: Works with php-cs-fixer, which is already a common dependency in PHP projects (including Laravel).
• No breaking changes: Purely a linter/autofixer, so no risk to runtime behavior.

Technical Risk

• Low risk:
  • Dependency risk: Relies on php-cs-fixer (stable, widely adopted).
  • Configuration risk: Custom rules (if any) are documented in the package, but the default aligns with PSR-12.
  • Performance impact: Zero runtime overhead; only runs during CI or local dev.
• Potential pitfalls:
  • Rule conflicts: If the project already uses a different coding standard (e.g., custom rules), conflicts may arise.
  • CI/CD integration: Requires adding a step to run php-cs-fixer in pipelines (but this is a best practice anyway).

Key Questions

1. Does the project already use php-cs-fixer?
   • If yes, assess rule overlap/conflicts.
   • If no, evaluate whether this adds value over existing standards (e.g., Laravel’s default PSR-12).
2. Are there custom coding rules beyond PSR-12?
   • If so, ensure they align with this package’s defaults or extend it via php-cs-fixer config.
3. How is code quality enforced today?
   • If no linter is used, this is a high-opportunity addition.
   • If one exists, compare strictness and coverage.
4. CI/CD readiness:
   • Can the team easily add php-cs-fixer to their pipeline?
   • Are there existing failures that would block adoption?

Integration Approach

Stack Fit

• Native PHP/Laravel compatibility: Works with any PHP 8.0+ project (Laravel 8+ recommended).
• Toolchain alignment:
  • Integrates with composer, php-cs-fixer, and CI tools (GitHub Actions, GitLab CI, etc.).
  • Compatible with Laravel’s Pint (if used) but provides stricter/alternative rules.
• No framework-specific dependencies: Pure PHP, no Laravel-specific hooks.

Migration Path

1. Assessment phase:
   • Run vendor/bin/php-cs-fixer fix --dry-run to preview changes.
   • Check for conflicts with existing .php-cs-fixer.dist.php or .editorconfig.
2. Pilot phase:
   • Apply to a single module (e.g., tests/ or a feature branch).
   • Validate CI/CD integration (add a step to fail builds on violations).
3. Full rollout:
   • Update .php_cs.dist to include all relevant paths (src/, app/, etc.).
   • Enforce in PR checks (e.g., GitHub Actions workflow).

Compatibility

• Backward compatibility: Safe to adopt incrementally; no breaking changes to existing code.
• Rule customization:
  • Extend via php-cs-fixer config (e.g., add risky rules or disable specific fixes).
  • Override defaults by merging configs (e.g., keep existing .php-cs-fixer.dist.php).
• IDE support: Works with PHPStorm, VSCode (via php-cs-fixer plugins).

Sequencing

1. Pre-requisite: Ensure php-cs-fixer is installed (composer require --dev friendsofphp/php-cs-fixer).
2. Step 1: Add innmind/coding-standard to composer.json (dev dependency).
3. Step 2: Create .php_cs.dist with target paths.
4. Step 3: Add CI check (e.g., GitHub Actions):

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

5. Step 4: Gradually enforce in PRs, then merge requests.

Operational Impact

Maintenance

• Low maintenance burden:
  • Rules are static (PSR-12 + Innmind’s extensions).
  • Updates can be version-pinned or auto-updated via composer.
• Dependency updates:
  • Monitor php-cs-fixer major versions for breaking rule changes.
  • Innmind’s rules may evolve; track via GitHub releases.

Support

• Developer onboarding:
  • Simple to explain ("Run php-cs-fixer before committing").
  • Documentation is minimal but sufficient (leverages php-cs-fixer docs).
• Troubleshooting:
  • Common issues: False positives, rule misconfigurations.
  • Debug with --dry-run and --verbose flags.

Scaling

• Performance:
  • Minimal overhead; runs only during dev/CI.
  • Large codebases may see longer CI times (mitigate with parallelization or caching).
• Team adoption:
  • Scales well for teams already using php-cs-fixer.
  • Resistance may come from strictness (e.g., line length, braces) but can be adjusted.

Failure Modes

• CI failures:
  • Flaky tests if rules are too strict (mitigate with gradual enforcement).
  • False positives in legacy code (address via config overrides).
• Tooling conflicts:
  • Overlaps with pint or other formatters (resolve by standardizing on one tool).
• Rule drift:
  • If Innmind updates rules, projects may need to sync (version pinning helps).

Ramp-Up

• Time to value: <1 day for setup; immediate feedback in CI.
• Key milestones:
  1. Day 1: Install and run locally.
  2. Day 2: Add to CI and fix critical violations.
  3. Week 1: Full enforcement in PRs.
• Training needed:
  • Basic php-cs-fixer usage (e.g., --fix, --diff).
  • How to customize rules if defaults are too strict/lenient.