Psalm Tester Laravel Package

Product Decisions This Supports

• Enhancing Code Quality Gates: Integrate Psalm static analysis into CI/CD pipelines as a mandatory pre-merge check, ensuring type safety and catching regressions early. This aligns with initiatives to shift left on quality.
• Test-Driven Static Analysis: Adopt a test-first approach for Psalm, where expected analysis outcomes are verified in unit tests (e.g., PsalmTestCase::assertNoErrors()). This supports a culture of explicit quality contracts in the codebase.
• Build vs. Buy: Buy (adopt this package) to avoid reinventing wheel for Psalm integration in tests/CI. The lightweight nature reduces maintenance overhead compared to custom scripts or full-fledged solutions like PHPStan’s testers.
• Use Cases:
  • CI/CD Enforcement: Fail builds on new Psalm errors, with clear diffs for developers.
  • Regression Prevention: Baseline Psalm output in tests to detect unintended changes (e.g., after refactors).
  • Onboarding: Standardize Psalm usage across teams with a consistent interface (e.g., Psalm::run()->assertNoErrors()).
  • Laravel-Specific: Leverage for Laravel packages where type safety is critical (e.g., service containers, event handlers).

When to Consider This Package

• Adopt if:

  • Your team uses Psalm for static analysis but lacks reproducible, testable execution in CI/tests.
  • You want to fail builds on new Psalm errors with actionable feedback (e.g., diffs, line numbers).
  • Your project prioritizes type safety and regression prevention (e.g., large codebases, shared libraries).
  • You prefer minimal setup over heavyweight tools (e.g., no need for custom scripts or complex configurations).

• Look Elsewhere if:

  • You use PHPStan instead of Psalm (this package is Psalm-specific).
  • Your team lacks CI/CD maturity or doesn’t treat static analysis as a gated requirement.
  • You need advanced features like IDE integration or detailed error explanations (consider Psalm’s core tooling or plugins).
  • Your project is small/trivial and Psalm isn’t a priority (manual checks may suffice).

How to Pitch It (Stakeholders)

For Executives:

*"This package lets us automate and enforce Psalm static analysis in our CI pipeline, catching type errors before they reach production. By treating Psalm results as testable assertions, we’ll:

• Reduce bugs from type-related issues (e.g., null dereferences, incorrect method calls).
• Save dev time by failing builds early with clear error diffs, not during QA.
• Lower maintenance costs by avoiding custom scripts—this is a drop-in solution with minimal overhead. Think of it as unit tests for your code’s type safety—just as critical as functional tests."

For Engineering:

*"phpyh/psalm-tester gives us a clean, testable interface for Psalm in CI and local dev. Key wins:

• Reproducible runs: No more ‘works on my machine’ issues with Psalm output.
• Regression safety: Baseline Psalm errors in tests to catch unintended changes (e.g., after refactors).
• Seamless CI integration: Fail builds on new errors with actionable output (e.g., Psalm::run()->assertNoErrors()).
• Laravel-friendly: Works out-of-the-box with Laravel’s testing tools (e.g., PHPUnit). Setup is trivial—just add the package and start asserting Psalm results like tests. Let’s use this to harden our type safety without extra tooling debt."*

Call to Action: "Let’s pilot this in our next major release for critical paths (e.g., API services, shared libraries) and expand based on impact. Target: 0 new Psalm errors in CI by [date]."