Larastan Laravel Package

Product Decisions This Supports

• Shift from reactive to proactive code quality: Integrate static analysis into the CI/CD pipeline to catch bugs before they reach testing or production. Reduces debugging time and improves developer velocity.

  • Example: Enforce Level 5 (strict) checks in phpstan.neon for new features while allowing baseline exceptions for legacy code.

• Leverage Laravel’s ecosystem: Build a type-safe foundation for new projects or migrate legacy codebases to modern PHP practices (e.g., stricter typing, fewer runtime errors).

  • Use case: New microservices or monolith refactors where runtime exceptions (e.g., undefined methods, type mismatches) are costly.

• Developer experience (DX) investment: Reduce context-switching for engineers by automating error detection during local development (e.g., via Git hooks or IDE plugins like PHPStorm integration).

  • Feature flag: Enable --generate-baseline for legacy projects to gradually improve code quality without blocking work.

• Build vs. buy: Avoid custom static analysis tools (high maintenance) by adopting Larastan’s Laravel-specific extensions (e.g., Eloquent, Blade, Facades). Saves ~6–12 months of dev effort.

  • ROI: Estimated 30–50% reduction in runtime bugs for Laravel apps after 3 months of enforcement.

• Roadmap alignment:

  • Phase 1: Integrate into CI (e.g., GitHub Actions) with Level 3 checks.
  • Phase 2: Enforce Level 5 for new PRs; baseline legacy code.
  • Phase 3: Extend to third-party packages (via orchestra/testbench).

When to Consider This Package

Adopt Larastan if:

• Your team uses Laravel 11.15+ and PHP 8.2+ (or Laravel 9+ with v1.x).
• You prioritize proactive bug detection over reactive debugging.
• Your codebase has high complexity (e.g., deep Eloquent relationships, Blade templates, or custom Facades).
• You’re migrating legacy PHP to stricter typing or modern Laravel practices.
• Your CI/CD pipeline has bandwidth for static analysis (adds ~5–15 mins to builds).

Look Elsewhere if:

• You’re not using Laravel (Larastan is Laravel-specific).
• Your team lacks PHPStan experience (steep learning curve for config tuning).
• You need runtime performance analysis (use Blackfire or Xdebug instead).
• Your project is tiny (<5K LoC) with minimal Laravel magic (overhead may not justify benefits).
• You’re constrained by CI time budgets (Larastan can be slow on large codebases; optimize with --memory-limit or parallel runs).

How to Pitch It (Stakeholders)

For Executives:

*"Larastan is like a pre-flight check for our Laravel code—it catches critical bugs before they crash production or slow down developers. For example, it would’ve flagged [insert real-world bug, e.g., a missing Eloquent relationship or undefined Facade method] that cost us [X hours/downtime]. By integrating this into our CI pipeline, we can:

• Reduce debugging time by 30–50% (studies show static analysis catches 40% of bugs early).
• Improve onboarding for new engineers with fewer runtime surprises.
• Future-proof our codebase as we adopt stricter typing (aligns with PHP 8.2+ trends).

Ask: Can we pilot this on [Project X] for 2 sprints to measure bug reduction? Budget: ~$0 (open-source); ROI: ~$Y in saved dev time."*

For Engineering Teams:

*"Larastan supercharges PHPStan to understand Laravel’s magic—like Eloquent models, Blade views, and Facades—so it stops treating them as ‘undefined.’ Here’s how we’ll use it:

• CI Integration: Run phpstan analyse on PRs (Level 3) and merges (Level 5).
• Local Dev: Add a Git hook to catch errors early (like ESLint for JS).
• Legacy Code: Use --generate-baseline to gradually tighten rules without blocking work.

Why now?

• Fixes [pain point, e.g., ‘We spend 20% of sprints debugging MethodNotFoundException’].
• Works with our existing tooling (PHPStorm, GitHub Actions).
• Zero runtime overhead—only runs during dev/CI.

Next steps:

1. Install via composer require --dev larastan/larastan.
2. Configure phpstan.neon (I’ll share a template).
3. Run locally to see what it catches!

Example win: It’ll flag this anti-pattern in 10 seconds:

// ❌ Larastan catches this:
$user->role->permissions; // role() might return null!
// ✅ Fixed with:
$user->role?->permissions;
```"*

---
### **For Developers:**
*"Larastan is your **PHPStan sidekick for Laravel**—it understands:
- Eloquent models (e.g., `User::where('active', true)->get()`).
- Blade templates (e.g., missing translations).
- Facades (e.g., `Cache::get('key')` without null checks).

**How to start**:
1. Install:
   ```bash
   composer require --dev larastan/larastan

2. Add to phpstan.neon:

   includes:
       - vendor/larastan/larastan/extension.neon
   level: 5
   paths:
       - app/
   

3. Run:

   ./vendor/bin/phpstan analyse
   

Pro tip: Use @phpstan-ignore-line for false positives, but aim to fix 80%—it’ll make your code more robust.

What to expect:

• False positives? Check Larastan’s ignore list.
• Slow? Try --memory-limit=2G or run on specific files.
• Need help? Slack me or check the docs."*