Psalm Laravel Package

Product Decisions This Supports

• Shift from reactive to proactive quality assurance: Integrate Psalm into CI/CD pipelines to catch type-related bugs (e.g., null dereferences, incorrect method calls) before they reach production, reducing debugging time and incident severity.
• Enforce stricter coding standards: Use Psalm’s mutability annotations (@psalm-pure, @psalm-mutation-free) to enforce functional programming patterns, improving testability and security (e.g., taint tracking for XSS/SQLi).
• Reduce technical debt: Prioritize Psalm’s MissingPureAnnotation/MissingImmutableAnnotation issues in backlog grooming sessions to systematically improve codebase maintainability.
• Build vs. buy: Avoid custom static analysis tools by leveraging Psalm’s extensibility (plugins, custom rules) instead of reinventing wheel for PHP-specific checks.
• Security-first roadmap: Use Psalm’s taint analysis (e.g., TaintedLlmPrompt) to proactively block injection vulnerabilities in APIs handling user input (e.g., LLMs, database queries).
• Developer experience (DX): Integrate Psalm with IDEs (PhpStorm, VSCode) via plugins to provide real-time feedback, reducing context-switching to CI logs.

When to Consider This Package

Adopt Psalm if:

• Your PHP codebase is medium-to-large (10K+ LoC) with critical business logic (e.g., payment processing, user auth).
• You lack comprehensive unit/test coverage for edge cases (e.g., null checks, type mismatches).
• Your team prioritizes security (e.g., OWASP Top 10 risks like injection, broken access control).
• You’re using PHP 8.0+ (Psalm’s type system aligns closely with modern PHP features like enums, attributes).
• You need scalable static analysis without runtime overhead (Psalm runs in milliseconds).

Look elsewhere if:

• Your codebase is small/trivial (Psalm’s value diminishes for <5K LoC).
• You rely on dynamic PHP features (e.g., eval(), create_function()) that Psalm can’t analyze.
• Your team lacks buy-in for type annotations (Psalm’s power depends on gradual adoption).
• You need real-time runtime analysis (use Xdebug or Taint Analysis tools like PHPStan’s taint-analysis plugin).
• Your stack is heavily framework-specific (e.g., legacy Symfony 2) with unsupported Psalm plugins.

How to Pitch It (Stakeholders)

For Executives:

*"Psalm is a self-service static analysis tool that acts like a ‘PHP linter on steroids’—catching bugs early to save dev time and reduce outages. For example, it found [X] critical null-dereference bugs in [Module Y] during our pilot, which would’ve cost [Z] hours to debug in production. By integrating Psalm into our CI, we’ll:

• Cut debugging time by 30% (via preemptive bug detection).
• Improve security posture by blocking injection flaws (e.g., SQLi/XSS) before they’re exploited.
• Future-proof the codebase with stricter typing, making onboarding easier and tech debt manageable. Investment: Minimal (open-source, MIT-licensed); ROI via reduced fire drills and faster feature delivery."*

For Engineering:

*"Psalm is PHPStan’s stricter, more opinionated cousin—focused on mutability and security rather than just type correctness. Key wins:

• Automated refactoring: Run --alter to auto-fix MissingPureAnnotation issues, turning impure functions into pure ones (better for testing/parallelization).
• Security superpowers: Detects tainted data flows (e.g., user input leaking into SQL queries) via TaintedLlmPrompt and other custom rules.
• IDE integration: Get real-time feedback in PhpStorm/VSCode (no more waiting for CI).
• Plugin ecosystem: Extend with custom rules (e.g., business-logic-specific checks) or use existing ones for Laravel/Symfony. Tradeoff: Steeper learning curve than PHPStan, but pays off for large/complex codebases. Start with --init to generate a config, then ramp up with --issues=VeryWeakType."*

For Developers:

*"Psalm is like TypeScript for PHP—it’ll yell at you for:

• Passing null where a string is expected.
• Forgetting to check array keys before access.
• Writing impure functions that mutate globals (hard to test!). How to start:

1. Install: composer require vimeo/psalm.
2. Run: ./vendor/bin/psalm --init (generates config).
3. Fix critical issues first: ./vendor/bin/psalm --issues=TypeError,Nullability.
4. Enable mutability checks: ./vendor/bin/psalm --issues=MissingPureAnnotation. Pro tip: Use --show-snippets to see exactly what’s wrong—no more guessing!"*