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. The package now provides a foundational, testable interface for Psalm, enabling teams to enforce type safety programmatically with zero additional tooling debt. The initial release establishes this capability with a clean, Laravel-friendly API, making it a production-ready starting point for Psalm adoption.

• Test-Driven Static Analysis: Adopt a test-first approach for Psalm, where expected analysis outcomes are verified in unit tests (e.g., Psalm::run()->assertNoErrors()). This supports a culture of explicit quality contracts in the codebase. The package’s design allows for baselining Psalm errors in tests, ensuring regressions are caught immediately after refactors or new commits.

• Build vs. Buy: Buy (adopt this package) to avoid reinventing the 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. This is now a production-ready starting point for Psalm adoption, with minimal setup and Laravel-native compatibility.

• Use Cases:

  • CI/CD Enforcement: Fail builds on new Psalm errors, with clear diffs for developers. The package’s design ensures consistent, reproducible Psalm execution in automated pipelines, now with assertion-based validation for CI integration.
  • Regression Prevention: Baseline Psalm output in tests to detect unintended changes (e.g., after refactors). The initial release provides the tools to assert Psalm compliance as part of the test suite, enabling automated regression detection.
  • Onboarding: Standardize Psalm usage across teams with a consistent interface (e.g., Psalm::run()->assertNoErrors()). The package’s Laravel integration lowers the barrier to adoption, making it ideal for team-wide enforcement.
  • Laravel-Specific: Leverage for Laravel packages where type safety is critical (e.g., service containers, event handlers). The initial release is tailored for Laravel’s ecosystem, including PHPUnit compatibility and minimal configuration requirements.

When to Consider This Package

• Adopt if:

  • Your team uses Psalm for static analysis but lacks reproducible, testable execution in CI/tests. This package now provides the minimal, functional building blocks to address this gap, with assertion-based validation for Psalm results.
  • You want to fail builds on new Psalm errors with actionable feedback (e.g., diffs, line numbers). The package’s design ensures clear, testable assertions for CI integration, now with first-class support for Laravel’s testing ecosystem.
  • Your project prioritizes type safety and regression prevention (e.g., large codebases, shared libraries). The initial release is a low-risk entry point for Psalm adoption, with zero additional tooling debt.
  • You prefer minimal setup over heavyweight tools (e.g., no need for custom scripts or complex configurations). The package is lightweight and Laravel-native, requiring only basic configuration and seamless PHPUnit integration.
  • You are starting fresh with Psalm or need a simple, standardized way to integrate it into your workflow. This is the first official release, making it ideal for early adopters seeking a test-driven approach to static analysis.

• Look Elsewhere if:

  • You use PHPStan instead of Psalm (this package is Psalm-specific). No change here—this remains a Psalm-only solution.
  • Your team lacks CI/CD maturity or doesn’t treat static analysis as a gated requirement. The package assumes CI integration is a priority; manual checks may still be preferable for less mature workflows.
  • You need advanced features like IDE integration or detailed error explanations. The initial release is focused on CI/test integration, not replacing Psalm’s core tooling.
  • Your project is small/trivial and Psalm isn’t a priority. Manual checks or ad-hoc scripts may still suffice for low-complexity codebases.
  • You require custom Psalm configurations or plugins. This package provides basic execution and assertion capabilities but does not extend Psalm’s core functionality.

How to Pitch It (Stakeholders)

For Executives:

*"This new Laravel 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) with zero additional tooling debt.
• Save dev time by failing builds early with clear error diffs, not during QA—like unit tests for type safety.
• Lower maintenance costs by avoiding custom scripts. This is a drop-in solution with minimal setup, tailored for Laravel. This is a low-risk pilot opportunity: Start with critical paths (e.g., API services, shared libraries) and expand based on impact. Target: 0 new Psalm errors in CI by [date], with measurable improvements in code stability. The package’s assertion-based validation ensures we can baseline and track regressions automatically, further reducing technical debt."

For Engineering:

*"phpyh/psalm-tester (v0.1.0) 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—assert Psalm results like tests using Psalm::run()->assertNoErrors().
• Regression safety: Baseline Psalm errors in tests to catch unintended changes (e.g., after refactors). Example:

  Psalm::run()->assertNoErrors(); // Fails if new errors are introduced.
  

• Seamless CI integration: Fail builds on new errors with actionable output, integrated with Laravel’s testing tools. The package is Laravel-native and requires no additional configuration.
• Test-driven workflow: Treat Psalm like a first-class citizen in your test suite, ensuring type safety is continuously verified. Setup is trivial—just install the package and start asserting Psalm results. This is the official, supported way to test Psalm compliance in Laravel. Let’s use it to harden our type safety without reinventing the wheel."

Call to Action: *"Let’s pilot this in our next major release for high-impact areas (e.g., API services, shared libraries). Proposal:

1. Week 1: Add the package to a single module; configure CI to fail on new Psalm errors. Use assertNoErrors() to baseline current state.
2. Week 2: Expand to critical paths; measure reduction in type-related bugs. Leverage assertion-based validation to track regressions.
3. Week 3: Review impact and roll out to remaining teams. Goal: No new Psalm errors in CI by [date], with a 50% reduction in type-related production issues within 3 months. The package’s test-driven approach ensures we can continuously enforce type safety as part of our existing workflows."