Technical Evaluation

Seamless Laravel Integration: Larastan is a PHPStan extension specifically designed for Laravel, leveraging its Service Container, Eloquent ORM, Blade templates, and magic methods (e.g., dynamic properties, facades). This makes it a native fit for Laravel applications, reducing friction in static analysis.
Complementary to Existing Tooling: Works alongside PHPStan, Psalm, and Laravel’s built-in testing without redundancy. Unlike runtime testing, it preemptively catches bugs (e.g., undefined methods, type mismatches) before execution.
Modular Design: Supports custom rules, PHPDoc types, and configuration overrides, allowing TPMs to tailor analysis to project-specific needs (e.g., ignoring legacy code via baselines).

Low-Coupling: Installs as a dev dependency (composer require --dev larastan/larastan) and requires minimal configuration (phpstan.neon). No core Laravel modifications are needed.
PHPStan Dependency: Requires PHPStan 2.1.28+, which must be installed separately. This is a blocker for teams not already using PHPStan.
Laravel Version Lock: Supports Laravel 11.16+ (v3.x). Older versions require downgrading to v1.x/v2.x, which may introduce compatibility risks with newer PHPStan features.
Memory Intensive: Large codebases may hit memory limits (default: 512MB). Mitigated via --memory-limit=2G flag or parallel analysis (PHPStan’s --parallel).

Risk Area	Mitigation Strategy
False Positives	Use baseline files to exclude legacy errors; configure `ignoreErrors` in `phpstan.neon`.
Performance Overhead	Run in CI/CD pipelines (e.g., GitHub Actions) with cached dependencies.
Configuration Complexity	Start with level 5 (default) and incrementally raise severity. Use docs/rules.md for Laravel-specific rules.
Dependency Conflicts	Pin PHPStan version in `composer.json` to avoid breaking changes.
Blade/Template Parsing	Ignore dynamic Blade content (e.g., `@{{ }}`) via `excludePaths` or PHPDoc ignores.

Adoption Readiness:
- Is the team already using PHPStan/Psalm? If not, what’s the cost of onboarding (training, CI setup)?
- What’s the baseline PHPStan level (1–12)? Larastan’s effectiveness scales with stricter levels.
CI/CD Integration:
- How will failures be triaged (e.g., Slack alerts, PR checks)?
- Should analysis run on every push or nightly to avoid CI bottlenecks?
Legacy Code Strategy:
- Will a baseline file be generated to phase out errors incrementally?
- Are there excluded paths (e.g., third-party libraries, tests)?
Developer Experience:
- How will error messages (e.g., stack traces) be surfaced (CLI, IDE plugins like PHPStorm)?
- Will custom PHPDoc types (e.g., @var Collection<int, User>) be documented for the team?
Scaling:
- For monorepos, how will parallel analysis be configured?
- Will migration caching (enableMigrationCache) be enabled to speed up repeated runs?

Integration Approach

Primary Stack: Laravel 11.16+ with PHP 8.2+.
Secondary Stack:
- PHPStan/Psalm: Larastan extends PHPStan’s type system. If using Psalm, consider vimeo/psalm-laravel instead.
- IDE Support: Integrates with PHPStorm, VSCode (PHP Intelephense), and Laravel IDE Helper.
- Testing Tools: Complements PestPHP, PHPUnit, and Laravel’s artisan test.
Anti-Patterns:
- Avoid mixing with runtime type checkers (e.g., spatie/laravel-type-checker) to prevent redundancy.
- Do not use for performance-critical paths (static analysis adds no runtime overhead, but configuration may).

Preparation Phase:
- Audit Laravel version (must be ≥11.16 for v3.x).
- Install dependencies:
```
composer require --dev phpstan/phpstan:^2.1.28 larastan/larastan:^3.0
```
- Set up phpstan.neon with Larastan’s extension:
```
includes:
    - vendor/larastan/larastan/extension.neon
```
Incremental Rollout:
- Start with level 5 (default) and baseline generation:
```
./vendor/bin/phpstan analyse --generate-baseline
```
- Configure CI/CD (e.g., GitHub Actions) to run on main/develop branches.
- Gradually raise PHPStan level (e.g., from 5 → 7 → 10) while fixing errors.
Post-Launch:
- Add custom rules (e.g., NoPublicModelScopeAndAccessorRule) via phpstan.neon.
- Document ignored errors (e.g., errors-to-ignore.md) for onboarding.

Component	Compatibility Notes
Laravel Packages	Works with most packages, but highly dynamic code (e.g., `spatie/laravel-activitylog`) may need ignores.
Custom Macros	Larastan does not parse macros by default. Use `@phpstan-ignore-line` or configure `ignoreErrors`.
Blade Templates	Supports basic Blade syntax but may miss dynamic content (e.g., `@{{ $user->name }}`).
Database Migrations	Supports raw SQL, ENUM types, and UUID/ULID via `foreignUuid`.
Event Listeners	Resolves event classes and payload types if properly typed.

Phase 1 (0–2 Weeks):
- Install and configure Larastan.
- Generate baseline and fix critical errors (e.g., undefined methods).
Phase 2 (2–4 Weeks):
- Integrate with CI/CD.
- Raise PHPStan level and address medium-severity errors.
Phase 3 (Ongoing):
- Customize rules (e.g., NoMissingTranslationsRule).
- Train developers on PHPDoc annotations and ignoring errors.

Configuration Drift: phpstan.neon may need updates with Laravel/PHPStan major versions. Use dependency pinning to minimize surprises.
Rule Updates: Larastan releases new rules (e.g., NoPublicModelScopeAndAccessorRule) every 1–2 months. Subscribe to release notes to adopt improvements.
Deprecation Risk: PHPStan’s breaking changes (e.g., v2 → v3) may require Larastan updates. Monitor PHPStan’s changelog.

Error Triaging:
- Use stack traces (--error-format=github) for debugging.
- Refer to Larastan’s docs/rules.md for rule-specific fixes.
Community Resources:
- GitHub Discussions: Active community for Laravel-specific issues.
- PHPStan Docs: General static analysis best practices.
SLA Considerations:
- Blockers: Critical errors (e.g., Call to undefined method) should be fixed within 1 sprint.
- Non-Blockers: PHPDoc suggestions can be deferred.

Large Codebases:
- Parallel Analysis: Use --parallel to distribute analysis across CPU cores.
- Path Filtering: Exclude vendor/, tests/, or legacy/ directories to reduce runtime.
Monorepos:
- Configure per-project phpstan.neon files.
- Use PHPStan’s projectPaths to analyze multiple apps in one run.
Performance:
- Migration Caching: Enable enableMigrationCache: true to avoid re-parsing migrations.
- **Memory Limits