Plugin Laravel Laravel Package

Technical Evaluation

Architecture Fit

• Laravel-Native Static Analysis: The plugin is purpose-built for Laravel, leveraging its framework-specific patterns (facades, Eloquent, Blade, etc.) to provide deep type inference and taint tracking. This aligns perfectly with Laravel’s architecture, where dynamic method calls (e.g., DB::statement()) and magic properties (e.g., Eloquent relationships) dominate.
• Complementary to Existing Tools: Unlike generic PHP analyzers (e.g., PHPStan), this plugin specializes in Laravel’s ecosystem, filling gaps left by tools like Larastan (e.g., taint analysis for security vulnerabilities). It integrates seamlessly with Psalm’s type system, avoiding redundancy.
• Security-First Design: The taint analysis is dataflow-aware, tracking user input across function boundaries—critical for Laravel apps where user data often flows through layers (e.g., controllers → services → repositories → queries). This is more robust than pattern-matching tools (e.g., regex-based scanners) or generic PHP analyzers.

Integration Feasibility

• Low Friction: Installation is a single composer require command, with minimal configuration (enable the plugin via CLI). No runtime overhead or code modifications are needed.
• Psalm Dependency: Requires Psalm (v5+), which may necessitate adoption if not already in use. However, Psalm’s type checking is already a best practice for Laravel projects targeting PHP 8.2+.
• Version Compatibility: Supports Laravel 9–13 and PHP 8.0–8.2, with clear upgrade paths. Legacy support (Laravel <9) is deprecated but may still work for older projects.
• Baseline Handling: Critical for existing codebases—first runs will flag many issues. The plugin provides a baseline mechanism to suppress known issues incrementally, which is essential for large-scale adoption.

Technical Risk

• False Positives/Negatives: Taint analysis is context-sensitive. For example:
  • False Positives: Escaping functions (e.g., e() for Blade) may not be annotated correctly, leading to overzealous warnings. The plugin mitigates this with @psalm-taint-escape + @psalm-flow rules, but custom logic (e.g., Html::entities()) might require manual stubs.
  • False Negatives: Complex taint flows (e.g., across services) may be missed if stubs are incomplete. The plugin’s contribution model encourages community-driven stub additions (e.g., for third-party packages).
• Performance: Taint analysis adds CPU overhead during static analysis. For large codebases, this could slow down CI pipelines. Mitigation: Run in parallel or limit to critical paths.
• Psalm Version Lock: Tied to Psalm’s roadmap. Breaking changes in Psalm (e.g., taint analysis API shifts) could require plugin updates. The plugin’s active maintenance (last release: 2026-04-07) reduces this risk.
• Custom Logic: Some Laravel patterns (e.g., dynamic facades, macroable classes) may require custom stubs or configuration. The plugin provides hooks for this but demands TPM oversight.

Key Questions

1. Adoption Barrier: Is Psalm already used in the team’s workflow? If not, will the security benefits justify the initial setup cost?
2. Codebase Maturity: How many legacy issues will the baseline suppress? Will the team commit to incremental cleanup?
3. Custom Framework Logic: Does the project use non-standard Laravel patterns (e.g., custom facades, unique taint sources)? If so, will stubs need extension?
4. CI Integration: How will analysis results be actioned (e.g., blocked PRs, Slack alerts)? Will false positives require manual triage?
5. Toolchain Synergy: How will this plugin coexist with other tools (e.g., Larastan, SonarQube)? Will results overlap or conflict?
6. Long-Term Maintenance: Who will update stubs if new Laravel versions or security sinks emerge? Is the team prepared to contribute or sponsor maintenance?

Integration Approach

Stack Fit

• Primary Use Case: Laravel applications using PHP 8.0+ and Psalm. Ideal for:
  • Security-critical apps (e.g., financial, healthcare, auth systems).
  • Large codebases where manual security reviews are impractical.
  • Teams adopting Psalm for type safety and now want to extend to security.
• Complementary Tools:
  • Larastan: Use alongside for type-specific checks (e.g., Eloquent relationships, Blade strings).
  • PHPUnit: Integrate with tests to block tainted code paths in CI.
  • GitHub Advanced Security: Use Psalm’s findings to enrich SAST reports.
• Anti-Patterns:
  • Avoid for small projects where manual reviews are feasible.
  • Not a replacement for runtime security (e.g., CSRF tokens, rate limiting).

Migration Path

1. Assessment Phase:
   • Run psalm --init to generate a config.
   • Enable the plugin: psalm-plugin enable psalm/plugin-laravel.
   • Baseline the codebase: psalm --set-baseline=psalm-baseline.xml to suppress existing issues.
2. Pilot Phase:
   • Start with high-risk areas (e.g., query builders, file uploads).
   • Configure errorLevel to 4 (low) initially, then increase to 1 (high).
   • Triage false positives (e.g., misannotated escaping functions).
3. Full Rollout:
   • Integrate with CI/CD (e.g., fail builds on TaintedSql errors).
   • Add custom stubs for project-specific taint sources/sinks.
   • Train developers on how to fix issues (e.g., using DB::raw() with bound parameters).

Compatibility

• Laravel Ecosystem:
  • Works with facades, Eloquent, Blade, and Artisan out of the box.
  • Supports package discovery (stubs for third-party packages like laravel/breeze).
• Psalm Configuration:
  • Extends existing Psalm configs (e.g., psalm.xml) with Laravel-specific rules.
  • No conflicts with PHPStan or Larastan (uses distinct annotation syntax).
• IDE Integration:
  • Psalm’s VS Code/PHPStorm plugins will highlight taint issues in real time.
  • GitHub Copilot can suggest fixes for common patterns (e.g., DB::raw() with placeholders).

Sequencing

Operational Impact

Maintenance

• Plugin Updates:
  • Automated: Use composer update with version constraints (e.g., ^4.0).
  • Breaking Changes: Monitor Psalm’s taint analysis API for shifts (e.g., new annotations).
• Stub Management:
  • Community-Driven: Encourage contributions for missing stubs (e.g., new Laravel packages).
  • Internal Stub Library: For proprietary logic, maintain a private stub repository.
• Configuration Drift:
  • Version Control: Commit psalm.xml and baseline files to avoid silent changes.
  • Documentation: Track custom rules/configs in a SECURITY.md or PSALM.md.

Support

• Developer Onboarding:
  • Training: 1-hour session on taint analysis basics (sources, sinks, escapes).
  • Cheat Sheet: List common fixes (e.g., "Use DB::raw() with placeholders for SQL").
• Issue Triage:
  • False Positive Workflow: Log recurring issues to the plugin’s GitHub repo.
  • Severity Tagging: Prioritize TaintedSql/TaintedShell over MissingTranslation.
• Tooling:
  • Slack Alerts: Integrate with psalm --report=github for real-time notifications.
  • Dashboards: Track trends (e.g., "Tainted issues per PR") in DataDog/Grafana.

Scaling

• Performance:
  • **Parallel