Coding Standards Laravel Package

Technical Evaluation

Architecture Fit

• Low Direct Impact: This package enforces coding standards (PSR-12, custom rules) via PHP_CodeSniffer and PHP-CS-Fixer, not a runtime dependency. It does not alter core Laravel/PHP functionality but enforces consistency in development workflows.
• Best Fit for:
  • Teams adopting strict coding standards (e.g., PSR-12, custom in-house rules).
  • CI/CD pipelines enforcing pre-commit hooks or gated PR checks.
  • Projects requiring auditability (e.g., compliance, onboarding new devs).
• Misalignment Risk:
  • Overhead for teams already satisfied with existing standards (e.g., no custom rules).
  • Minimal value if no automated enforcement is in place.

Integration Feasibility

• Easy to Adopt:
  • Install via Composer (composer require --dev neuecommerce/coding-standards).
  • Integrates with PHP_CodeSniffer (existing in Laravel via php-cs-fixer or laravel-pint).
  • Configurable via .php-cs-fixer.dist.php or custom rulesets.
• Dependencies:
  • Requires PHP_CodeSniffer (often pre-installed in Laravel projects).
  • No runtime impact—purely a dev tool.
• Customization:
  • Supports custom rules (if the package allows extensions).
  • Can override default PSR-12 rules if needed.

Technical Risk

• Low Risk:
  • MIT-licensed, minimal abstraction.
  • No breaking changes expected (standards enforcement is backward-compatible).
• Potential Pitfalls:
  • False Positives/Negatives: Custom rules may misalign with team expectations.
  • CI/CD Overhead: Strict checks could slow down PR pipelines if not cached.
  • Toolchain Conflicts: May clash with existing tools like pint or laravel-shift.

Key Questions

1. Why This Over Alternatives?
   • Does this package offer unique rules not covered by php-cs-fixer/pint?
   • Is the team already using PHP_CodeSniffer? If not, is there a need to standardize?
2. Enforcement Strategy
   • How will violations be handled? (e.g., block merges, require fixes in PRs)
   • Will this replace or supplement existing tools (e.g., pint)?
3. Customization Needs
   • Are there project-specific coding standards this package must enforce?
   • Can rules be toggled per project (e.g., legacy code exemptions)?
4. Performance Impact
   • How long do checks take in CI? (Critical for large codebases.)
   • Is parallelization or caching (e.g., GitHub Actions cache) planned?

Integration Approach

Stack Fit

• Native Compatibility:
  • Works with any PHP/Laravel project (no Laravel-specific dependencies).
  • Integrates with:
    • PHP_CodeSniffer (for static analysis).
    • PHP-CS-Fixer (for auto-fixing).
    • CI Tools: GitHub Actions, GitLab CI, Jenkins.
• Toolchain Synergy:
  • Complementary to:
    • laravel/pint (if using Laravel’s built-in formatter).
    • dealerdirect/phpcodesniffer-composer-installer (for PHPCS setup).
  • Avoid Redundancy:
    • If already using php-cs-fixer, assess overlap before adoption.

Migration Path

1. Assessment Phase:
   • Audit current coding standards (e.g., run phpcs with default rules).
   • Compare against this package’s rules (if documented).
2. Pilot Integration:
   • Install in dev dependencies:

     composer require --dev neuecommerce/coding-standards
     

   • Configure in php-cs-fixer.dist.php or .php-cs-fixer-baseline.php.
3. CI/CD Integration:
   • Add to pre-commit hooks (e.g., Husky + php-cs-fixer).
   • Enforce in CI (e.g., GitHub Actions):

     - name: Run coding standards
       run: vendor/bin/phpcs --standard=neuecommerce
     

4. Gradual Rollout:
   • Start with non-critical branches.
   • Phase out old standards tools if replacing them.

Compatibility

• PHP Version: Check if the package supports Laravel’s PHP version (e.g., 8.0+).
• Laravel Version: No direct dependency, but ensure php-cs-fixer is compatible.
• Tool Conflicts:
  • With pint: May duplicate efforts; prefer one tool.
  • With psalm/pest: No conflicts, but avoid redundant checks.

Sequencing

1. Pre-requisites:
   • Install php-cs-fixer and phpcodesniffer if missing.
   • Baseline current code (e.g., php-cs-fixer fix --diff).
2. Core Integration:
   • Configure package rules in composer.json or .php-cs-fixer.dist.php.
3. Enforcement:
   • Add to pre-commit (local) and CI (global).
4. Optimization:
   • Cache CI results (e.g., GitHub Actions).
   • Exclude legacy code if needed.

Operational Impact

Maintenance

• Low Ongoing Effort:
  • Rules are static (no runtime maintenance).
  • Updates via Composer (composer update neuecommerce/coding-standards).
• Deprecation Risk:
  • MIT license = low vendor lock-in, but abandonware risk (0 stars).
  • Monitor for upstream updates (e.g., new PHP versions).

Support

• Developer Onboarding:
  • Pros: Reduces "why is this code formatted like this?" questions.
  • Cons: New devs may need training on new rules.
• Troubleshooting:
  • Debugging false positives requires rule familiarity.
  • Limited community support (0 stars = no public issues/discussions).
• Documentation:
  • Assume minimal docs; may need to reverse-engineer rules from examples.

Scaling

• Performance:
  • Linear with codebase size (PHP_CodeSniffer scans all files).
  • Mitigate with:
    • Parallel CI jobs (e.g., split by directory).
    • Caching (store results between runs).
• Team Adoption:
  • Small teams: Easy to enforce.
  • Large teams: May need opt-in phases or rule exceptions.

Failure Modes

Ramp-Up

• Time to Value:
  • Day 1: Install and configure.
  • Week 1: Integrate with CI, train team.
  • Month 1: Full enforcement, adjust rules as needed.
• Key Metrics:
  • Reduction in code review time (fewer formatting debates).
  • Decrease in PR merge cycles (fewer "fix before merge" requests).
• Training Needs:
  • For Devs: How to run checks locally (./vendor/bin/phpcs).
  • For PMs: How to prioritize rule adjustments (e.g., business vs. technical rules).