Eloquent Criteria Laravel Package

Technical Evaluation

Architecture fit: The package remains a standard Composer-installed Laravel library with no architectural change in v2.0.0 — no new service providers, facades, config surfaces, or extension points are announced. Fit with our application architecture is therefore unchanged from v1.x. The only architectural variable introduced is the framework support window, which now excludes Laravel 9.

Integration feasibility: Straightforward for any service already on Laravel 10 or later: the upgrade is a version-constraint bump plus a dependency refresh. Integration is not feasible for services still on Laravel 9 without first performing a framework upgrade — this is the single gating item in the release and it is a hard gate, not a soft one.

Technical risk: Moderate, concentrated in two areas. (1) Dropping Laravel 9 is a breaking change delivered in a major version, which is correct semver hygiene but means Composer will not silently resolve v2 onto a Laravel 9 app — it will either fail or retain v1.x, depending on how constraints are declared. The dangerous case is a loose constraint (^1.0 || ^2.0 style, or *) where a composer update could attempt v2 and fail CI late. (2) "Update composer packages" is an unspecified transitive dependency refresh. Because the release notes give no dependency diff, security patch content, or changelog references, the blast radius of that line item is currently unknown and must be treated as unaudited.

Key questions:

• Which Laravel versions are supported in v2.0.0 — 10 only, 11 only, or 10 and 11+? The notes state only what was removed.
• What is the minimum PHP version now required, and did it move? This often changes alongside a Laravel floor bump.
• Which transitive packages were updated, to which versions, and do any of them carry their own breaking changes or deprecations?
• Does v2.0.0 contain only the removals and dependency bumps, or are there unlisted behavioral changes (bug fixes that alter output, default value changes)?
• Is v1.x still receiving security patches, and for how long? This determines whether staying on Laravel 9 is a viable short-term position or an immediate liability.
• Is there a published upgrade guide or CHANGELOG entry beyond the two-line release note?

Integration Approach

Stack fit: The package fits cleanly for services on Laravel 10+. For Laravel 9 services, fit is now broken at the major-version boundary and must be resolved at the framework layer, not the package layer. Any service pinned to Laravel 9 by an unrelated blocker (an unmaintained first-party dependency, an inherited legacy module) effectively inherits that blocker here too.

Migration path: Two legitimate paths, chosen per service:

1. Upgrade path (preferred): Bring the service to Laravel 10+ first, verify the framework upgrade independently, then bump this package to ^2.0. Sequenced this way, any regression is attributable to one change at a time.
2. Pin path (temporary): Constrain the package to ^1.x explicitly in composer.json — not left to resolution — and record the pin as deliberate technical debt with a review date tied to the v1.x support window.

What we must not do is allow implicit resolution. Every service's composer.json should carry an explicit constraint on this package so intent is visible in review, and lock files should be audited in the PR rather than regenerated wholesale.

Compatibility: Verify the Composer constraint string in each consumer before merging anything, and confirm the resolved version in composer.lock post-update. Confirm PHP version parity across CI images, local dev containers, and production runtime — a PHP floor bump buried inside "update composer packages" is a realistic and easily missed failure.

Sequencing: Enumerate consumers of the package first (this is the cheapest step and informs everything else). Classify each by current Laravel version. Land all upgrade-path services before touching the pin path, so the pin set is small and known. Roll out to a low-traffic service first, hold for a full release cycle, then proceed. Treat the dependency refresh as a separate change from the version bump where possible — if they land together, a regression gives you two suspects.

Operational Impact

Maintenance: Ongoing maintenance load is low and unchanged in character: routine version bumps within the v2 major line. The v1.x pin creates a deferred maintenance obligation — pinned services accumulate framework-version debt that compounds and becomes more expensive the longer it sits. Budget for the Laravel 9 exit explicitly rather than letting it drift.

Support: Support posture depends on an unconfirmed input: the v1.x end-of-life date. If v1.x receives security fixes for a defined window, the pin path is defensible and time-boxed. If Laravel 9 support was dropped with no ongoing v1.x maintenance, the pin path converts this package into a security liability for every Laravel 9 consumer and the timeline compresses sharply. Resolve this question before approving any pinned service.

Scaling: No scaling implications. The package surface did not change; there is no new runtime path, no new configuration, and no expected effect on throughput, memory, or deployment topology.

Failure modes: The realistic failure modes, ordered by likelihood:

• Silent version retention — a loose constraint resolves to v1.x without anyone noticing, creating a false sense of upgraded state. Mitigate with explicit constraints and lock-file review.
• CI-only failure — the constraint change passes locally but fails in CI due to a PHP or extension version floor introduced by the dependency refresh. Mitigate by aligning CI images before rollout.
• Transitive regression — a bumped dependency changes behavior in a code path we exercise indirectly. This is the lowest-probability but highest-cost mode, and it is invisible in the release notes as written. Mitigate with integration test coverage around package-touching code paths and a staged rollout.
• Blocked framework upgrade — a Laravel 9 service discovers its own blocker only after this work is scheduled, stranding the package upgrade. Mitigate by validating the framework upgrade path for each Laravel 9 consumer before committing to dates.

Ramp-up: Negligible. No new APIs, no new concepts, no new configuration to learn. An engineer familiar with Composer and Laravel version constraints can execute this without onboarding. The time cost is almost entirely coordination — enumerating consumers, sequencing rollouts, and closing out the Laravel 9 tail — rather than engineering effort.