Larastan Laravel Package

Technical Evaluation

Architecture Fit

• Seamless Laravel Integration: Larastan is a PHPStan extension designed specifically for Laravel, leveraging its dependency injection container, Eloquent models, and magic methods (e.g., dynamic properties, fluent interfaces). This makes it a native fit for Laravel applications, avoiding the need for invasive refactoring.
• Static Analysis Without Runtime Overhead: Unlike traditional testing, Larastan performs code analysis at build/development time, catching type-related bugs (e.g., undefined methods, incorrect return types) before execution. This aligns with modern shift-left testing practices.
• Complementary to Existing Tooling: Works alongside Laravel IDE Helper, Pint, and PHPStan, reinforcing a type-safe Laravel ecosystem. Can be integrated into CI/CD pipelines for pre-commit checks.

Integration Feasibility

• Low Friction Setup: Requires only three steps (Composer install, phpstan.neon config, and CLI execution), with minimal Laravel-specific adjustments.
• Backward Compatibility: Supports Laravel 11.15+ (and older versions with v1/v2), ensuring gradual adoption in legacy projects.
• Customization Depth: Offers fine-grained configuration (e.g., migration scanning, model property checks, config type validation), allowing tailored analysis for monolithic or modular apps.
• Performance Considerations:
  • Memory Intensive: Large codebases may require --memory-limit adjustments (e.g., 2G).
  • Migration Scanning Overhead: Analyzing migrations and schema dumps adds initial setup time but improves model property inference.

Technical Risk

Key Questions for TPM

1. Adoption Scope:
   • Should Larastan be mandatory for all devs (pre-commit hooks) or optional (CI-only)?
   • How will legacy code (pre-Laravel 9) be handled? (Baseline files or phased enforcement?)
2. Configuration Management:
   • Should phpstan.neon be version-controlled or environment-specific?
   • How will team-specific ignores (e.g., per-developer ignoreErrors) be managed?
3. Performance Trade-offs:
   • Is the migration scan worth the overhead, or should disableMigrationScan be default?
   • Should enableMigrationCache be enabled in CI (faster) vs. local dev (always fresh)?
4. Toolchain Integration:
   • How will Larastan integrate with existing linters (e.g., PHP-CS-Fixer, Pest)?
   • Should it trigger automated PHPDoc generation (e.g., via laravel-ide-helper)?
5. Monitoring & Compliance:
   • How will error trends (e.g., new vs. fixed issues) be tracked over time?
   • Should blocking failures be enforced in CI (e.g., fail builds on new errors)?

Integration Approach

Stack Fit

• Core Stack: Works natively with Laravel 11+, PHP 8.2+, and PHPStan.
• Complementary Tools:
  • IDE Support: Integrates with PHPStorm, VSCode (via PHPStan extension) for real-time feedback.
  • CI/CD: Plugs into GitHub Actions, GitLab CI, or CircleCI for pre-merge analysis.
  • Testing: Can reduce test suite maintenance by catching type errors early.
• Anti-Patterns:
  • Avoid mixing with runtime type checkers (e.g., assert()) that may conflict with static analysis.
  • Do not use for runtime validation—Larastan is not a replacement for tests or input sanitization.

Migration Path

Compatibility

• Laravel Ecosystem:
  • Eloquent: Supports models, relationships, accessors/mutators, and casts.
  • Collections: Detects undefined methods and type mismatches.
  • Service Container: Resolves bindings and interfaces correctly.
• Third-Party Packages:
  • May require custom PHPDoc types (e.g., for package-specific classes).
  • TestBench support for package development.
• Edge Cases:
  • Dynamic Proxies (e.g., Eloquent models): Larastan handles these via container resolution.
  • Macros/Concerns: May need explicit PHPDoc annotations for full coverage.

Sequencing

1. Setup Phase:
   • Install Larastan (composer require --dev larastan/larastan).
   • Configure phpstan.neon with minimal rules (level: 1).
   • Generate a baseline (phpstan analyse --generate-baseline).
2. Validation Phase:
   • Run analysis on critical paths (e.g., API routes, core services).
   • Fix high-impact errors (e.g., undefined methods, type mismatches).
3. Optimization Phase:
   • Enable advanced rules (checkModelProperties, checkConfigTypes).
   • Adjust performance settings (enableMigrationCache, disableSchemaScan).
4. Enforcement Phase:
   • Integrate with CI/CD (fail builds on new errors).
   • Document ignored errors in phpstan.neon with justification.

Operational Impact

Maintenance

• Configuration Drift:
  • Risk: phpstan.neon may diverge across environments.
  • Mitigation: Use template files (e.g., phpstan.neon.dist) and CI validation.
• Rule Updates:
  • Larastan follows PHPStan’s release cycle—monitor for breaking changes.
  • Upgrade Strategy: Test new versions in a staging environment before rolling out.
• Deprecation:
  • Laravel deprecations (e.g., old magic methods) may require Larastan rule updates.

Support

• Developer Onboarding:
  • Training: Document common errors (e.g., NoUnnecessaryCollectionCall) and how to fix them.
  • IDE Setup: Ensure PHPStorm/VSCode is configured to show Larastan errors.
• Error Triage:
  • False Positives: Maintain a centralized list of ignored errors with rationale.
  • Legacy Code: Use baseline files to isolate old issues from new code.
• Community Resources:
  • Leverage Larastan’s docs (rules.md, errors-to-ignore.md) for troubleshooting.

Scaling

• Large Codebases:
  • Parallel Analysis: Use --parallel flag for faster runs (if PHPStan supports it).
  • Modular Configs: Split phpstan.neon by domain/module to reduce scan scope.
• Performance Tuning:
  • Disable Unneeded Scans: Use disableMigrationScan or disableSchemaScan if irrelevant.
  • Memory Limits: Adjust --memory-limit based on CI vs. local dev needs.
• Distributed Teams:
  • CI Parallelism: Run Larastan in parallel with other checks (e.g., tests, linting).