Doctrine Inspectors Laravel Package

Technical Evaluation

Architecture fit. smartassert/doctrine-inspectors is a PHP library for reflecting over Doctrine ORM entity metadata — it is not a Laravel package in the framework sense (no service provider, config, or facade). In a Laravel codebase it sits on the test/tooling side of the boundary, used by assertion libraries and custom test helpers that need to inspect entity properties, associations, and types. That makes it a low-blast-radius dependency: it does not participate in the request lifecycle, so architectural coupling to the application is effectively nil.

Integration feasibility. Straightforward via Composer (^4.0), but gated on PHP 8.4. The 4.0 changelog is composed entirely of CI and developer-tooling work — local php-cs-fixer, PER-latest instead of PSR-12, PHPStan ^2, PHPUnit ^12, PHP 8.4 — with no described runtime API changes. That is the central concern: a major version bump whose published rationale is tooling-only usually means the breaking change is the platform floor (PHP 8.4) plus dependency-resolution shifts, and it is undocumented in the notes.

Technical risk. Moderate, concentrated in version adoption rather than runtime behaviour:

• phpstan ^2 and phpunit ^12 are dev dependencies and should not propagate to consumers, but they will affect anyone running --prefer-lowest or resolving against a shared dev dependency set; PHPUnit 12 also implies PHP 8.3+ for the test toolchain.
• The switch from PSR-12 to PER-latest is cosmetic for consumers but signals a formatting baseline change that will churn any in-repo patches or forks.
• The absence of a stated BC break means the real one must be discovered. Assume Doctrine ORM constraint ranges moved; verify against the pinned ORM minor.
• Single-maintainer project (@webignition); release cadence appears driven by CI hygiene rather than consumer demand.

Key questions. What is the actual consumer-facing BC break in 4.0 — is it only PHP 8.4? Did the Doctrine ORM version constraint change? Is 3.x still receiving patches, and for how long? Are there signature changes in the inspector entry points, or is the major bump purely a platform-floor decision? Does the package declare php: ^8.4 in require or require-dev?

Integration Approach

Stack fit. Only viable where the runtime is PHP 8.4. Laravel applications on 8.2/8.3 (the current LTS-adjacent defaults for many teams) cannot adopt 4.0; they stay on 3.x. Confirm this against the actual composer.json constraint rather than the release notes, since a dev-only 8.4 bump would look identical in the changelog.

Migration path. Treat 3.x → 4.0 as a platform upgrade, not a code migration. Steps: (1) verify the host application's PHP version and Laravel release support PHP 8.4; (2) diff the 3.0...4.0 tree for src/ changes — if the only diffs are .github/, .php-cs-fixer.*, composer.json, and phpunit.xml, the upgrade is dependency-only; (3) bump the constraint, run the full test suite, and specifically exercise any custom inspectors or assertion helpers that call into this library; (4) pin the exact version until the runtime behaviour is confirmed identical.

Compatibility. Check transitive Doctrine ORM ranges and whether the library's require block narrowed. If it now requires an ORM major/minor the application has not adopted, the upgrade is blocked behind a Doctrine upgrade — a much larger piece of work than the changelog implies.

Sequencing. Adopt in a test-only branch first, on a single service, behind an exact pin. Do not adopt as part of a broader dependency refresh; keep it isolated so a rollback is a one-line constraint change. If multiple services share a monorepo, upgrade them together to avoid two Doctrine toolchain versions in one CI matrix.

Operational Impact

Maintenance. Low carrying cost — no runtime surface, no migrations, no configuration. The maintenance burden is almost entirely in keeping the constraint current with the platform, and in re-verifying after each release that the tooling-only changelog is honest.

Support. No formal support policy is stated. The 3.x line's continued patch coverage is unknown, which matters if the organisation cannot move to PHP 8.4 on the required timeline. Treat 3.x as unsupported-by-default and plan the platform upgrade accordingly.

Scaling. Negligible. Inspection is a build/test-time operation; it does not affect request throughput, memory, or deployment topology. The only scaling concern is CI: PHPUnit 12 and PHPStan 2 in the shared toolchain may require CI image updates across every pipeline that resolves this dependency.

Failure modes. (1) Silent CI breakage from the PHPUnit 12 / PHPStan 2 toolchain shift rather than from library code; (2) resolution failures in projects pinned below PHP 8.4 — these surface at composer update, not at runtime, which is the benign case; (3) inspection errors on proxy or uninitialised Doctrine entities, unchanged from 3.x but worth regression-testing since behaviour is not asserted in the notes; (4) fork/overlay drift if the team carries local patches against PSR-12 formatting.

Ramp-up. Minimal for any engineer already comfortable with Doctrine metadata. The library is small and the API is narrow. The real ramp-up cost is organisational — coordinating a PHP 8.4 platform upgrade across services if 4.0 is deemed necessary, which is a platform decision rather than a package decision.