Coding Standard Laravel Package

Technical Evaluation

Architecture Fit

• Purpose Alignment:

  • The package remains a PHP coding standard configuration (PSR-12-based or custom E-Lodgy rules) for static analysis tools like PHP_CodeSniffer and now PHPStan (new in v1.1.6).
  • Key Update: PHPStan integration (PR #48) expands its utility beyond linting to static analysis, enabling deeper codebase scrutiny (e.g., type safety, logical errors).
  • Laravel Fit: Still agnostic to Laravel but now aligns better with modern PHP tooling stacks (e.g., PHPStan is widely adopted for Laravel projects).
  • Custom Rules Risk: PHPStan rules may introduce Laravel-specific conflicts (e.g., facade usage, dynamic properties). Audit required.

• Tooling Ecosystem:

  • New Capabilities:
    • PHPStan: Adds static analysis (e.g., level: 5 for strict checks). Requires PHPStan setup (composer require --dev phpstan/phpstan).
    • Trailing Comma Fix: PR #47 suggests minor syntax rule updates (low impact).
  • Dependencies:
    • PHPUnit: Updated to ^9.6.x (no breaking changes; Laravel projects typically use PHPUnit for testing).
    • GitHub Actions: Minor update (actions/checkout@v4; irrelevant to Laravel integration).

Integration Feasibility

• Enhanced Feasibility:

  • PHPStan Integration: Lowers barrier to adoption if the team already uses PHPStan (common in Laravel for type safety).
  • No Breaking Changes: Dependency updates (PHPUnit) are patch/minor versions; no Laravel compatibility risks.
  • Steps Updated:
    1. Install phpcs + phpstan.
    2. Configure both tools to use this standard (e.g., phpstan.neon + phpcs.xml).
    3. Add to CI/CD (e.g., GitHub Actions with phpstan and phpcs steps).

• Customization Risk:

  • PHPStan Rules: May flag Laravel patterns as "errors" (e.g., dynamic properties in facades). Requires rule overrides in phpstan.neon.
  • Mitigation: Test against a Laravel codebase pre-integration; document exceptions.

Technical Risk

Key Questions

1. PHPStan Adoption Readiness:

   • Is the team already using PHPStan? If not, what’s the cost of setup (learning curve, configuration)?
   • Are there Laravel-specific PHPStan rules (e.g., for facades, service containers) that need exclusion?

2. Rule Compatibility:

   • Does this standard’s PHPStan config conflict with Laravel’s dynamic features (e.g., __get(), magic methods)?
   • Example: Will phpstan:disallowDynamicProperties break Illuminate\Support\Facades\Log?

3. Enforcement Strategy:

   • Should PHPStan run at level 5 (strict) or a lower level (e.g., 3) to avoid false positives?
   • How will legacy code (e.g., pre-Laravel 8) be handled?

4. Long-Term Viability:

   • With PHPStan now included, is E-Lodgy actively maintaining this package? (Last release: 2024, but PRs are recent.)
   • Should the team fork to customize PHPStan rules for Laravel?

Integration Approach

Stack Fit

• Target Tools:

  • Primary: PHP_CodeSniffer (phpcs) + PHPStan (new).
  • Secondary: laravel-pint (for auto-fixing) or rector (for refactoring).
  • CI/CD: GitHub Actions/GitLab CI with parallel steps for phpcs and phpstan.

• Laravel-Specific Considerations:

  • PHPStan: May need custom extensions for Laravel (e.g., phpstan/extension-installer for framework-specific rules).
  • Synergy:
    • Use phpstan for type safety and phpcs for style.
    • Leverage pint to auto-fix phpcs violations pre-commit.

Migration Path

1. Assessment Phase (2–3 weeks):

   • Install phpstan and phpcs locally.
   • Run against Laravel codebase to identify:
     • PHPStan false positives (e.g., facades, dynamic properties).
     • PHP_CodeSniffer conflicts (e.g., custom naming rules).
   • Compare with existing tools (e.g., psr12, symfony).

2. Pilot Phase (3–4 weeks):

   • Integrate PHPStan as warnings in CI (non-blocking).
   • Integrate phpcs as warnings; gather team feedback.
   • Document common exceptions (e.g., app/Providers/FacadeServiceProvider).

3. Full Rollout (2–3 weeks):

   • Enforce PHPStan at level 3 (blocking in CI).
   • Enforce phpcs as blocking.
   • Deprecate old standards (e.g., psr12 alone).

Compatibility

• PHP Version: Compatible with Laravel’s PHP 8.1+ (PHPStan 1.0+ requires PHP 8.0+).
• Laravel Version: Agnostic; works with Laravel 8+.
• Tooling Conflicts:
  • PHPStan: May flag:
    • Illuminate\Support\Facades\Log::info() (dynamic calls).
    • Magic methods (__get, __set) in service providers.
  • Solution: Add to phpstan.neon:

    excludes:
      - app/Providers/FacadeServiceProvider.php
    

Sequencing

Operational Impact

Maintenance

• Pros:
  • PHPStan Integration: Adds value beyond linting (e.g., catching bugs early).
  • Low Maintenance: MIT license; fork if E-Lodgy abandons it.
• Cons:
  • Rule Drift: PHPStan rules may evolve; require periodic updates.
  • Custom Overrides: Laravel-specific exclusions must be documented and version-controlled.

Support

• Developer Experience:
  • Positive: PHPStan catches logical errors (e.g., undefined methods) early.
  • Negative: Overly strict PHPStan rules may frustrate developers (e.g., facade usage).
• Onboarding:
  • New hires benefit from consistent style + static analysis.
  • Requires documentation on:
    • Running phpstan and phpcs locally.
    • Interpreting errors (e.g., "Cannot call method X on null").
• Support Burden:
  • Low: Most issues are self-service (fix via IDE or CLI).
  • High-Severity: Rare; typically requires rule overrides or CI configuration tweaks.

Scaling

• Performance Impact:
  • PHPStan: Adds ~5–15 minutes to CI (depends on codebase size; cache results).
  • PHP_CodeSniffer: ~1–5 minutes (parallelizable).
• Parallelization:
  • Run phpstan and phpcs in parallel CI jobs.
  • Cache phpstan results (e.g., GitHub Actions cache).
• Large Codebases:
  • May require rule exclusion for legacy/third-party code.
  • Consider incremental adoption (e.g., start with app/ directory).

Failure Modes