Doctrine Inspectors Laravel Package

Product Decisions This Supports

• Static analysis of Doctrine metadata at build time, not runtime. This package inspects Doctrine entity mappings (associations, inversed/owning sides, join columns, discriminators) so CI can fail on broken mapping graphs before a migration is ever run. That makes it a correctness gate on schema-touching work, not a runtime dependency.
• Roadmap gating for Doctrine-backed Laravel services. If any part of the estate uses laravel-doctrine/doctrine/orm alongside Eloquent, this is the low-cost way to keep mapping drift out of production. Useful as a decision input for "do we keep Doctrine, migrate to Eloquent, or run both" — the inspector's output quantifies how tangled the existing mapping graph already is.
• Build vs. buy: strong buy (i.e. adopt). Reimplementing entity-graph validation is days of work for a solved problem. The cost here is a dev dependency and a CI step.
• Release 4.0 itself is a decision point, not a feature win. The changelog contains zero product changes: PHP CS Fixer localisation, PSR-12 → PER-CS, PHPStan ^2, PHPUnit ^12, PHP 8.4, and CI repair. Product read: the maintainer is doing hygiene, which is a positive maintenance signal, but also that the library is feature-stable and in caretaker mode. Do not put roadmap weight on upstream adding capabilities; budget for the PHP floor it now imposes.
• Primary practical impact is a platform constraint. PHP 8.4 as the floor means this is unusable on any service still on 8.1–8.3. It becomes a forcing function for the PHP upgrade roadmap: adopt the tool after the runtime bump, or pin to 3.0 on older services and accept running two versions.

When to Consider This Package

Adopt when:

• The codebase uses Doctrine ORM (directly or via laravel-doctrine) and mapping correctness is currently validated only by "does the app boot" or by integration tests that touch a live schema.
• You want mapping errors to surface in CI as fast static failures rather than as runtime MappingExceptions in staging.
• Your platform baseline is PHP 8.4+ — this is now a hard requirement, not a soft one. Confirm the CI image and the oldest supported service both satisfy it before evaluating.
• You are willing to track a young-ish, single-maintainer package (smartassert/*) as a dev-only dependency, and to vendor/pin it.

Look elsewhere when:

• The stack is Eloquent-only. This package has essentially no value without Doctrine metadata.
• You are on PHP ≤ 8.3 and cannot upgrade soon — stay on 3.x, or skip.
• You need rich, maintained tooling with broad community support and documentation; the Doctrine ecosystem's own doctrine/orm validate-schema command and phpstan-doctrine cover a large overlapping surface with far more users and examples.
• You need runtime introspection/guarantees. This is a static-analysis-era dev tool; it does not protect production at request time.

How to Pitch It (Stakeholders)

For executives: A small, free open-source library that catches broken database-mapping definitions in our automated build instead of in production. Cost is near zero — a dev dependency and a CI step — and the payoff is fewer staging/production surprises on schema changes. The 4.0 release adds no new capability; it refreshes the maintainer's tooling and, importantly, requires PHP 8.4. So the real decision is not "should we use this" but "is our PHP 8.4 upgrade on schedule" — if yes, this is a cheap quality win we should take; if no, we defer and lose nothing today.

For engineering: 4.0 is a housekeeping major: PER-CS replaces PSR-12, PHPStan moves to ^2, PHPUnit to ^12, CI fixed, and the runtime floor is now PHP 8.4. Treat it as a breaking bump for platform reasons, not API reasons — expect dependency-resolution and static-analysis-baseline churn, not code rewrites. Recommended path: pin 3.x on services below PHP 8.4, adopt 4.x on services already there, run it as a non-blocking CI job for one sprint to see the real error volume, then promote it to blocking. Caveats to state plainly: single-maintainer project, minimal docs, and meaningful overlap with phpstan-doctrine and doctrine:validate-schema — sequence it alongside those rather than as a replacement.