Larastan Strict Rules Laravel Package

Technical Evaluation

Architecture Fit

• Opinionated Static Analysis: The package enforces strict Laravel-specific coding standards via PHPStan, aligning well with teams prioritizing maintainability, testability, and explicit dependency management (e.g., no facades, no dynamic where clauses). This fits architectures emphasizing explicitness over convenience (e.g., DDD, clean code, or large-scale monoliths).
• Complementary to Larastan: Designed to work with Larastan, a Laravel extension for PHPStan, ensuring compatibility with existing static analysis pipelines.
• Rule Granularity: Rules target anti-patterns (e.g., facade misuse, dynamic queries) that often introduce hidden complexity or runtime errors, making it ideal for quality-focused teams.

Integration Feasibility

• Low Friction: Requires only:
  1. Composer install (--dev).
  2. PHPStan config inclusion (rules.neon).
  3. Optional: Fine-tuning via parameters (e.g., whitelisting global functions).
• No Runtime Overhead: Pure static analysis; zero impact on production performance.
• Toolchain Synergy: Works seamlessly with:
  • CI/CD: Fail builds on violations (e.g., GitHub Actions, GitLab CI).
  • IDE Integration: PHPStan’s IDE plugins (e.g., PHPStorm, VSCode) highlight issues in real-time.
  • Pre-commit Hooks: Tools like PHP-CS-Fixer or Husky can enforce rules before commits.

Technical Risk

• Breaking Changes: Rules may flag legitimate patterns as violations (e.g., dynamic where clauses for complex queries, facades for global services like Auth). Requires incremental adoption (enable rules one-by-one).
• False Positives/Negatives:
  • Example: NoDynamicWhereRule might misfire on dynamic relations (fixed in v2.2.3).
  • Mitigation: Test against a representative codebase before full rollout.
• Dependency Risks:
  • Relies on Larastan (v3.x+) and PHPStan 2.0+. Ensure your stack supports these versions.
  • Minor version updates may introduce edge cases (e.g., v3.0.0’s Larastan 3.0 compatibility).

Key Questions for TPM

1. Adoption Strategy:
   • Should rules be enabled all-at-once (risky) or gradually (e.g., start with NoFacadeRule)?
   • How will the team handle violations? (Refactor vs. disable rules?)
2. Toolchain Compatibility:
   • Is Larastan already in use? If not, what’s the migration path?
   • Are there existing PHPStan rules (e.g., phpstan/extension-installer) that conflict?
3. Performance Impact:
   • Will PHPStan analysis time increase significantly? (Benchmark with phpstan --memory-limit=1G --generate-report.)
4. Team Readiness:
   • Is the team familiar with PHPStan? If not, budget time for onboarding.
   • Are developers open to stricter rules? (Survey or pilot group first.)
5. Customization Needs:
   • Will whitelisting (e.g., allowedGlobalFunctions) be required for legacy code?
   • Are there domain-specific exceptions to rules (e.g., allow facades in CLI commands)?

Integration Approach

Stack Fit

• Laravel Ecosystem: Optimized for Laravel (v8+; tested with Testbench). Works with:
  • PHP 7.3+ (minimum).
  • Laravel 8+ (implicitly, via Larastan compatibility).
  • Modern PHPStan: Leverages PHPStan 2.0+ features (e.g., generic class checks in v2.2.5).
• Static Analysis Tools:
  • Larastan: Required for Laravel-specific extensions (e.g., Eloquent model analysis).
  • PHPStan Baselines: Useful for ignoring known violations during migration.
• IDE/Editor Support:
  • Integrates with PHPStan IDE plugins (e.g., phpstan-phpstorm).

Migration Path

1. Prerequisites:
   • Upgrade to Larastan 3.x and PHPStan 2.0+ (if not already using them).
   • Install dependencies:

     composer require --dev nunomaduro/larastan phpstan/phpstan
     

2. Incremental Setup:
   • Phase 1: Add to composer.json (dev dependency).
   • Phase 2: Include rules.neon in PHPStan config:

     includes:
         - vendor/canvural/larastan-strict-rules/rules.neon
     

   • Phase 3: Enable rules gradually (e.g., start with noFacade: true).
3. Configuration:
   • Disable all rules initially:

     parameters:
         larastanStrictRules:
             allRules: false
     

   • Re-enable rules individually as the team adapts:

     parameters:
         larastanStrictRules:
             noFacade: true
             noGlobalLaravelFunction: true
             allowedGlobalFunctions: [auth, cache]
     

4. Testing:
   • Run PHPStan in CI with --level=max to catch violations early.
   • Use --generate-report to track progress over time.

Compatibility

• Laravel Versions:
  • Tested with Laravel 8+ (via Testbench). For older versions, check Larastan compatibility.
• PHPStan Extensions:
  • May conflict with other extensions (e.g., phpstan/laravel). Resolve via:
    • Priority: Order includes in phpstan.neon (later entries override earlier ones).
    • Whitelisting: Explicitly allow/deny rules per namespace.
• Legacy Code:
  • Use PHPStan baselines to ignore violations temporarily:

    vendor/bin/phpstan analyse --generate-baseline
    

Sequencing

1. Pilot Project:
   • Test on a non-critical module (e.g., a feature branch) before full adoption.
2. Rule Prioritization:
   • Start with low-effort, high-impact rules:
     • NoFacadeRule (easy to refactor).
     • ListenerShouldHaveVoidReturnTypeRule (clear intent).
   • Avoid high-refactor-cost rules early (e.g., NoDynamicWhereRule for complex queries).
3. CI Integration:
   • Fail builds on critical rules (e.g., facades, validation in controllers) first.
   • Gradually add other rules as the team adapts.

Operational Impact

Maintenance

• Rule Updates:
  • Monitor Larastan and PHPStan for breaking changes (e.g., v3.0.0’s Larastan 3.0 requirement).
  • Update dependencies regularly (e.g., via Dependabot).
• Custom Rules:
  • Extend or override rules via PHPStan’s extension-classes if needed.
• Documentation:
  • Maintain a runbook for common violations (e.g., "How to refactor facades").

Support

• Onboarding:
  • Provide cheat sheets for rule-specific fixes (e.g., "Replace Auth::user() with dependency injection").
  • Example:

    Rule	Common Fix	Example
    NoFacadeRule	Use constructor injection	public function __construct(private UserRepository $users)
    NoDynamicWhereRule	Use query scopes or static methods	Model::whereActive()->get()

• Debugging:
  • PHPStan’s error messages are detailed; pair with Larastan’s docs for Laravel-specific issues.
  • Use --error-format=github for CI-friendly output.

Scaling

• Performance:
  • PHPStan analysis time scales with codebase size. Mitigate with:
    • Parallelization: Use --parallel flag.
    • Caching: Enable PHPStan’s result cache (--cache-result).
    • Incremental Analysis: Focus on changed files (--files src/).
• Team Adoption:
  • Pair Programming: New hires should onboard with a senior dev familiar with the rules.
  • Code Reviews: Enforce rules via PR templates (e.g., "Did you remove any facades?").

Failure Modes