Psalm Laravel Package

Product Decisions This Supports

• Code Quality & Maintainability:

  • Adopt static analysis as a core part of the development workflow (e.g., CI/CD integration) to reduce runtime errors and improve developer productivity.
  • Enforce stricter type safety in PHP projects, aligning with modern best practices (e.g., gradual typing, nullable types).
  • Automate refactoring for large-scale codebase migrations (e.g., namespace changes, method/property moves) to reduce manual effort and human error.

• Developer Experience (DX):

  • Reduce onboarding friction for new engineers by surfacing type-related issues early (e.g., missing return types, undefined variables).
  • Enable "self-healing" codebases via Psalter to automatically fix common issues (e.g., adding type hints, removing unused code), reducing technical debt.
  • Support gradual adoption of PHP 8+ features (e.g., union types, attributes) by leveraging Psalm’s backward-compatibility checks.

• Engineering Efficiency:

  • Build vs. Buy Decision:
    • Buy: Psalm is a mature, open-source alternative to commercial tools like PHPStan or InstaPHP, with no vendor lock-in and active maintenance.
    • Build: If Psalm lacks specific custom rules (e.g., domain-specific validation), extend it via plugins or contribute to the project.
  • CI/CD Pipeline Integration:
    • Block merges for code with critical type errors (e.g., InvalidReturnType, PossiblyUndefinedVariable).
    • Use --diff mode to speed up CI runs by only analyzing changed files.
  • Refactoring at Scale:
    • Migrate namespaces, rename classes/methods, or align docblocks with actual types without manual intervention.

• Use Cases:

  • Legacy Code Modernization: Gradually add type hints to untyped PHP codebases.
  • Large-Scale Refactoring: Move classes between namespaces or split monolithic files into microservices.
  • Security & Reliability: Catch potential bugs (e.g., null dereferences, type mismatches) before production.
  • Team Onboarding: Standardize code quality across teams with automated enforcement of type rules.

When to Consider This Package

• Adopt Psalm if:

  • Your PHP codebase is medium-to-large (Psalm shines with scale; small projects may not need static analysis).
  • You prioritize type safety and want to reduce runtime errors without sacrificing flexibility (e.g., gradual typing).
  • You need automated refactoring tools for migrations (e.g., namespace changes, method moves).
  • Your team is already using PHP 7.4+ (Psalm’s features like union types and attributes are most useful here).
  • You want open-source with active maintenance (MIT license, community-driven).

• Look Elsewhere if:

  • Your project is trivial (e.g., a small script or prototype) where static analysis adds overhead.
  • You need deep IDE integration (Psalm has CLI tools but lacks real-time IDE plugins like PHPStan’s).
  • Your codebase is heavily dynamic (e.g., eval, dynamic class generation) where static analysis is unreliable.
  • You require custom business logic validation beyond type checking (consider custom PHPStan rules or Symfony’s Property Access).
  • Your team resists tooling adoption (Psalm’s learning curve may require buy-in from developers).

How to Pitch It (Stakeholders)

For Executives (Business/Technical Leaders)

"Psalm is a force multiplier for our engineering team, turning static analysis from a 'nice-to-have' into a core productivity driver. Here’s why it’s a no-brainer:

• Reduces Bugs in Production: Catches type-related errors before they reach users, saving costly fire drills (e.g., null pointer exceptions, type mismatches).
• Accelerates Refactoring: Automates large-scale code migrations (e.g., moving namespaces, renaming classes) that would otherwise take months of manual work. For example, we could split our monolithic App\Utils namespace into microservices in days, not weeks.
• Lowers Technical Debt: Tools like Psalter auto-fix common issues (e.g., adding missing return types, removing dead code), letting engineers focus on high-value work.
• Future-Proofs the Codebase: Enables gradual adoption of PHP 8+ features (e.g., union types, attributes) without breaking legacy systems.
• Open-Source & Cost-Effective: No licensing fees—just one-time setup and ongoing maintenance (vs. commercial tools like SonarQube).

Ask: ‘What’s the cost of not catching these bugs early? Psalm pays for itself in saved developer time and fewer outages.’

Proposal: Pilot Psalm in CI for 2 critical modules, measure bug reduction, then roll out company-wide. Budget: $0 (open-source) + 1 engineer-week for setup."

For Engineering Leaders (CTOs, Tech Leads)

"Psalm is the missing link between PHP’s dynamic nature and modern type safety. Here’s how it fits into our stack:

• Complements Existing Tools:
  • Works alongside PHPUnit (catches issues tests miss) and Symfony (for dependency injection validation).
  • Integrates with GitHub Actions/CI to block merges with critical type errors.
• Developer Experience Wins:
  • Reduces context-switching: Engineers get actionable error messages (e.g., ‘This function claims to return int but may return null’).
  • Automates drudgery: Psalter can add type hints to 10,000+ lines of code in minutes, not hours.
• Performance:
  • Threaded analysis (--threads=8) speeds up runs on large codebases.
  • Incremental mode (--diff) cuts CI times by only analyzing changed files.
• Migration Path:
  • Start with non-strict mode to identify issues without blocking work.
  • Gradually tighten rules as the team adopts type hints.

Ask: ‘Where are we leaking the most time into debugging type-related bugs? Psalm can cut that by 50%.’

Next Steps:

1. Run Psalm in a sandbox (e.g., a non-critical module) to validate findings.
2. Integrate with CI as a pre-merge check (fail on exit code 2).
3. Train the team on interpreting Psalm errors (1-hour workshop).
4. Leverage Psalter to auto-fix low-hanging fruit (e.g., missing return types)."

For Developers (Individual Contributors)

"Psalm is like a co-pilot for your PHP code—it catches mistakes you’d miss, and even helps you write better code automatically. Here’s how it helps you daily:

• Fewer Surprises:
  • Ever spent hours debugging a null value that shouldn’t exist? Psalm flags potential null issues before runtime.
  • Example: It’ll tell you if a function claims to return int but might return string.
• Write Less Boilerplate:
  • Psalter can auto-generate type hints for you. No more manually adding :**string to every function.
  • Example: Run vendor/bin/psalter --issues=MissingReturnType to add return types to your entire codebase in one command.
• Refactor with Confidence:
  • Moving a class to a new namespace? Psalm’s refactoring tool (psalm-refactor) will update all references for you.
  • Example: vendor/bin/psalm-refactor --move "App\Old\*" --into "App\New" moves all classes and fixes imports.
• Learn as You Go:
  • Psalm explains its rules in plain English (e.g., ‘This variable might be undefined’).
  • Start with --no-cache to see all possible issues, then gradually tighten the config.
• Works with Your Workflow:
  • Run it locally (./vendor/bin/psalm) or in CI to catch issues early.
  • Use --diff to only analyze changed files (saves time in large repos).

Try This Today:

1. Install Psalm in your project: composer require vimeo/psalm.
2. Run it once: ./vendor/bin/psalm --init (generates a config file).
3. Fix one type of error