Doctrine Psalm Plugin Laravel Package

Product Decisions This Supports

• Enhancing Code Quality & Developer Experience (DX):

  • Adopt as part of a static analysis tooling roadmap to reduce runtime bugs tied to Doctrine ORM misuse (e.g., incorrect entity relationships, proxy mismatches, or metadata errors).
  • Justify investment in Psalm as a primary static analyzer (vs. PHPStan) by leveraging this plugin to improve Doctrine-specific type safety—critical for large Laravel/Symfony apps with complex domain models.
  • Build vs. Buy: Avoid reinventing custom Psalm plugins for Doctrine; this package directly addresses a high-opportunity pain point (false positives, proxy handling) with minimal maintenance overhead.

• Refactoring & Tech Debt Reduction:

  • Enable confident refactoring of Doctrine-heavy codebases by surfacing actionable type errors (e.g., invalid repository calls, missing @ORM\* annotations).
  • Prioritize for teams migrating from annotations to attributes (PHP 8+) or adopting Doctrine’s new metadata system—the plugin bridges Psalm’s understanding of both.

• CI/CD & Shift-Left Quality:

  • Integrate into pre-commit hooks or CI pipelines to fail builds on Doctrine-related type violations, reducing production incidents tied to ORM logic.
  • Pair with Laravel’s built-in testing tools (e.g., Pest, PHPUnit) to create a dual-layer safety net (runtime tests + static analysis).

• Scaling Developer Onboarding:

  • Reduce ramp-up time for new hires by automating common Doctrine pitfalls (e.g., proxy initialization, lazy-loading edge cases) via Psalm errors.
  • Use as a gateway to stricter typing in legacy codebases, gradually improving maintainability.

When to Consider This Package

• Adopt if:

  • Your Laravel/Symfony app heavily uses Doctrine ORM (e.g., 50%+ of business logic interacts with entities/repositories).
  • You’re investing in Psalm (or already use it) and want to reduce false positives in Doctrine-heavy code.
  • Your team refactors frequently or maintains a complex domain model where type safety is critical.
  • You’re migrating from annotations to attributes or adopting Doctrine’s new metadata system—this plugin ensures Psalm stays aligned.
  • You’re prioritizing CI/CD quality gates and want to catch ORM bugs before runtime (e.g., proxy issues, invalid queries).

• Look elsewhere if:

  • Your project rarely uses Doctrine ORM (e.g., mostly API-driven with Eloquent or no ORM).
  • You’re not using Psalm and lack the infrastructure to integrate it (e.g., PHPStan is already deeply embedded).
  • Your team prefers runtime testing over static analysis (though this is a risky trade-off for ORM-heavy apps).
  • You’re using Doctrine DBAL directly without ORM features (this plugin focuses on ORM patterns).
  • Your CI pipeline is already overloaded—this adds another static analysis step (assess trade-offs vs. existing tools).

How to Pitch It (Stakeholders)

For Executives (Business/ROI Focus):

"This plugin is a low-cost, high-impact way to reduce bugs in our Doctrine-heavy codebase. By integrating with Psalm, it catches ORM-related errors early—saving dev time on debugging and reducing production incidents. For example, it flags issues like incorrect entity relationships or proxy mismatches before they reach QA, which directly cuts our tech debt and support costs. The maintenance overhead is minimal (just a Composer dependency), and it aligns with our investment in static analysis tools. Given the 12.53 opportunity score and active development, this is a no-brainer for teams working on our core domain logic."

For Engineering (Technical Depth):

*"The weirdan/doctrine-psalm-plugin solves two critical pain points in our stack:

1. False Positives: Psalm struggles with Doctrine’s dynamic behavior (proxies, lazy-loading, metadata). This plugin teaches Psalm the ‘language’ of Doctrine, reducing noise in our static analysis.
2. Actionable Errors: It surfaces real bugs—like invalid repository calls or missing @ORM\* annotations—during CI, not in production. For example, it’ll catch cases where a proxy isn’t initialized properly, which is a common source of N+1 queries or runtime exceptions.

Why Psalm? We’re already using it for general typing, and this plugin extends its coverage to Doctrine. It’s lightweight (no runtime overhead), integrates seamlessly with our existing workflow, and has a strong signal-to-noise ratio for ORM-heavy code.

Implementation: Add it to psalm.plugin-sets, configure in psalm.xml, and run in CI. We can phase it in by starting with a strictness trial (e.g., --no-cache mode) to validate the value before enforcing it.

Alternatives? PHPStan has similar plugins, but Psalm’s type inference is more aggressive for Doctrine patterns, and this plugin is actively maintained (last release: Jan 2025)."*

For Developers (Day-to-Day Impact):

*"This plugin will save you hours of debugging by catching Doctrine issues early. Imagine:

• No more ‘Call to a member function getX() on null’ errors from lazy-loaded proxies—Psalm will warn you if a proxy isn’t initialized.
• Automatic type hints for repository methods (e.g., find() returns ?User instead of mixed).
• Clear errors when you forget to add @ORM\GeneratedValue or misconfigure relationships.

It’s like having a second pair of eyes for your ORM logic, but automated. And since it runs in CI, you’ll catch these issues before they block your PR.

How to use it:

1. Install via Composer: composer require --dev weirdan/doctrine-psalm-plugin.
2. Add to psalm.xml:

   <plugin_class>weirdan\DoctrinePsalmPlugin\Plugin</plugin_class>
   

3. Run ./vendor/bin/psalm—you’ll see fewer false alarms and more real Doctrine-related errors.

Pro Tip: Start with --no-cache to see the full impact, then adjust psalm.xml to ignore false positives after the plugin catches the real ones."*