Plugin Laravel Laravel Package

Technical Evaluation

Architecture Fit

• Highly Complementary: The plugin integrates seamlessly with Laravel’s existing ecosystem (facades, Eloquent, Request handling) while leveraging Psalm’s static analysis engine. It does not disrupt core Laravel architecture but enhances it with taint tracking and type narrowing, filling gaps left by tools like PHPStan or Larastan.
• Security-First Design: The taint analysis (SQLi, XSS, SSRF, etc.) operates at the data-flow level, not just pattern matching, making it uniquely valuable for security-critical applications (e.g., financial systems, SaaS platforms).
• Modular Extensibility: The plugin’s design allows for custom stubs and new checks, enabling TPMs to tailor it to niche use cases (e.g., domain-specific security rules).

Integration Feasibility

• Low Friction: Requires minimal setup (composer require, psalm-laravel init), with zero runtime overhead (pure static analysis).
• Laravel Version Alignment: Supports Laravel 12/13 (v4.x) and 11 (v3.x), with clear upgrade paths. Legacy support exists but is deprecated.
• Psalm Dependency: Requires Psalm 7.x (beta) or 6.x, which may necessitate CI/CD adjustments if not already in use.
• Complementary Tools: Works alongside Larastan (type checks) and PHPStan without conflicts, enabling a multi-layered static analysis pipeline.

Technical Risk

• False Positives/Negatives: Taint analysis, while advanced, may require baseline tuning (e.g., suppressing known-safe paths). The plugin mitigates this with:
  • Configurable errorLevel (1–8).
  • Baseline files (psalm-baseline.xml).
  • Per-call-site taint specialization (e.g., Js::encode()).
• Performance: Static analysis can be CPU-intensive for large codebases. Mitigation:
  • Incremental analysis (Psalm’s native feature).
  • CI caching (e.g., GitHub Actions cache).
  • Parallel execution (Psalm supports --workers).
• Psalm Version Lock: Beta dependency (Psalm 7.x) may introduce instability. Workaround: Pin to a stable release or monitor Psalm’s release cycle.
• Custom Logic Gaps: Some Laravel features (e.g., dynamic macros, package-specific facades) may need manual stubs or configuration tweaks.

Key Questions for the TPM

1. Security vs. Type Safety Tradeoff:
   • Should the team prioritize taint analysis (security) or type narrowing (refactoring)? Can both be adopted incrementally?
2. CI/CD Impact:
   • How will analysis time affect CI pipelines? Should it run on push (fast feedback) or PR (reduced noise)?
3. Toolchain Alignment:
   • Is Psalm already in use? If not, what’s the cost of adoption (learning curve, config migration)?
4. Customization Needs:
   • Are there domain-specific security rules (e.g., HIPAA compliance) that require plugin extensions?
5. Legacy Support:
   • If using Laravel <11, should the team upgrade or accept limited plugin support?
6. False Positive Handling:
   • What’s the acceptable rate of false positives? Will the team invest in baseline tuning?

Integration Approach

Stack Fit

• Primary Stack: Laravel (11–13) + PHP 8.2+.
• Secondary Stack:
  • Psalm 6.x/7.x: Required for plugin compatibility.
  • Larastan/PHPStan: Optional but recommended for type checks (psalm-laravel focuses on security).
  • GitHub Actions/GitLab CI: Native CI integration via psalm-laravel add github.
• Anti-Patterns:
  • Avoid mixing with other static analyzers that conflict (e.g., tools using @var annotations differently).
  • Avoid running on monorepos without isolation (Psalm’s project root detection may fail).

Migration Path

1. Assessment Phase:
   • Run ./vendor/bin/psalm-laravel analyze --level 8 to baseline existing issues.
   • Use ./vendor/bin/psalm --set-baseline=psalm-baseline.xml to suppress legacy problems.
2. Incremental Adoption:
   • Start with security-only mode (taint analysis) before enabling stricter type checks.
   • Gradually lower errorLevel (e.g., 8 → 4 → 1) to tighten rules.
3. CI Integration:
   • Use psalm-laravel add github for automated workflows.
   • Configure parallel execution (--workers) for large codebases.
4. Toolchain Sync:
   • If using Larastan, run it post-Psalm to avoid annotation conflicts.
   • For PHPStan, ensure no overlapping rules (e.g., view-string checks).

Compatibility

• Laravel Features:
  • ✅ Eloquent (models, relations, scopes, attributes).
  • ✅ Facades (Auth, Cache, Route, etc.).
  • ✅ Request handling (input(), query(), file()).
  • ✅ Taint sources/sinks (SQL, XSS, shell injection).
  • ⚠️ Custom Macros: May require manual stubs.
  • ⚠️ Dynamic Proxies: Limited support (e.g., HasFactory).
• Psalm Config:
  • Supports XML config and CLI overrides.
  • Extends Psalm’s issue handlers (e.g., TaintedSql, PossiblyUnusedMethod).

Sequencing

Operational Impact

Maintenance

• Low Ongoing Effort:
  • Plugin updates are semver-compliant (backward-compatible).
  • Automated CI checks reduce manual review burden.
• Configuration Drift:
  • psalm.xml may need updates for new Laravel features (e.g., attributes, dynamic properties).
  • Baseline files (psalm-baseline.xml) require occasional pruning.
• Dependency Management:
  • Psalm 7.x is in beta; monitor for stability.
  • Laravel version drops may require plugin upgrades.

Support

• Developer Onboarding:
  • Learning Curve: Moderate (familiarity with Psalm/PHPStan helps).
  • Documentation: Comprehensive (README, docs/security.md, docs/issues/).
  • Community: Active maintainer (@alies-dev) with responsive issue triage.
• Debugging:
  • psalm-laravel diagnose subcommand provides runtime introspection.
  • False positives can be suppressed via config or baseline files.
• Toolchain Conflicts:
  • Larastan/PHPStan: Coexist if rules are non-overlapping.
  • IDE Plugins: Psalm’s PHPStorm/VSCode integrations work out-of-the-box.

Scaling

• Performance:
  • Large Codebases: Use --workers and incremental analysis.
  • CI Timeouts: Run on pull requests only or use cache warming.
  • Memory: Psalm is not memory-intensive but may hit limits on 100K+ LOC projects.
• Distributed Teams:
  • Baseline files help standardize analysis across environments.
  • GitHub Actions provides consistent feedback.
• Monorepos:
  • Not officially supported; may require project isolation or custom config.

Failure Modes