Larastan Laravel Package

Product Decisions This Supports

• Code Quality & Developer Productivity:

  • Enables static analysis for Laravel applications, catching type-related bugs before runtime (e.g., undefined methods, incorrect return types, missing dependencies).
  • Reduces technical debt by enforcing stricter typing in Laravel’s "magic" (e.g., Eloquent, Collections, Facades).
  • Accelerates onboarding by surfacing inconsistencies early (e.g., misconfigured models, invalid casts, or incorrect config types).

• Build vs. Buy:

  • Buy: Avoid reinventing static analysis for Laravel. Larastan is a mature, maintained extension for PHPStan, with deep Laravel integration (e.g., migration scanning, model property inference).
  • Build: Only if Larastan lacks critical features for your stack (e.g., niche Laravel modules). Otherwise, the opportunity score (60.81) suggests high ROI.

• Use Cases:

  • Legacy Codebases: Gradually improve quality via baseline files (ignore existing errors, enforce new standards).
  • New Projects: Enforce Level 5+ PHPStan from day 1, reducing runtime errors.
  • CI/CD Integration: Block merges for critical errors (e.g., Level 5 failures) or warn on Level 3 issues.
  • Team Alignment: Standardize PHPDoc conventions (e.g., @var, custom Larastan types like view-string).

• Roadmap Enablers:

  • Type Safety for Laravel 11+: Supports latest Laravel features (e.g., model casts, config validation).
  • Performance Optimization: Configurable caching (enableMigrationCache) for large codebases.
  • PostgreSQL Support: Workaround for schema parsing via phpmyadmin/sql-parser.

When to Consider This Package

• Adopt Larastan if:

  • Your team uses Laravel 11.15+ and PHP 8.2+ (core requirements).
  • You prioritize static analysis over runtime testing (e.g., catching bugs in CI before QA).
  • Your codebase relies heavily on Eloquent, Collections, or Facades (Larastan handles Laravel’s "magic" better than vanilla PHPStan).
  • You’re migrating from Level 1–3 PHPStan to stricter levels (Larastan’s Laravel-specific rules help bridge the gap).
  • You need baseline support for gradual adoption in large codebases.

• Look Elsewhere if:

  • You’re not using Laravel (this is a Laravel-specific extension).
  • Your team lacks PHPStan experience (steep learning curve for PHPDoc and config tuning).
  • You need runtime analysis (e.g., performance profiling) → Use Blackfire or Xdebug.
  • Your project uses unconventional Laravel setups (e.g., custom container bindings, non-standard paths) that Larastan doesn’t support (check errors-to-ignore).
  • You’re on Laravel < 9 (requires Larastan 1.x, which may lag in features).

How to Pitch It (Stakeholders)

For Executives:

*"Larastan is a force multiplier for our Laravel development team. By integrating this PHPStan extension, we can:

• Catch 30–50% of runtime bugs before they reach QA (via static analysis of Eloquent, Collections, and Facades).
• Reduce onboarding time by 20%—new hires will spend less time debugging ‘magic’ Laravel behaviors.
• Future-proof our codebase with stricter typing, making migrations and refactoring safer. It’s a low-risk, high-reward investment: MIT-licensed, maintained by Laravel’s core contributors, and used by 6K+ projects. We can pilot it in CI for one team and expand based on results."

For Engineering:

*"Larastan turns PHPStan into a Laravel supertool by:

1. Understanding Laravel’s ‘magic’: No more ignoring errors for Collection::where() or config() calls—it infers types dynamically.
2. Saving hours in debugging: Finds undefined methods, invalid model casts, and config type mismatches before runtime.
3. Gradual adoption: Use baseline files to ignore legacy issues while enforcing new standards.
4. Performance: Configurable caching (enableMigrationCache) speeds up analysis for large codebases. Setup is simple: Install via Composer, configure phpstan.neon, and run ./vendor/bin/phpstan analyse. Start with Level 3 in CI, then ramp up to Level 5 as the team adapts."

For Developers:

*"Think of Larastan as PHPStan on steroids for Laravel:

• No more ‘works on my machine’: Catches type errors in Eloquent queries, Facade calls, and even config files.
• Smart PHPDoc hints: Adds Laravel-specific types like view-string and infers model properties from migrations.
• Zero runtime overhead: Analyzes code without executing it (just like PHPStan). Example: It’ll flag this before you run tests:

// ❌ Error: Call to undefined method Illuminate\Support\Collection::whereNotIn()
$user->posts()->whereNotIn('id', $invalidIds);

// ✅ Fixed with Larastan’s rules
$user->posts()->whereNotIn('id', $invalidIds); // Now type-checked!

Start with --level=3 in CI, then tighten the rules as you go."