Fluent Laravel Package

Product Decisions This Supports

• Build vs. buy for the persistence mapping layer: Fluent replaces XML/YAML/attribute mapping with a PHP DSL. If our entities are defined in package code, generated dynamically (multi-tenant, per-customer schema variation), or need mapping logic that attributes can't express, this is a genuine "buy" — it removes a custom in-house mapping abstraction we'd otherwise maintain.
• Roadmap sequencing for the 3.0.0 upgrade: 3.0.0 moves the package onto Doctrine DBAL 4. That is a breaking dependency jump, not a feature drop. Any roadmap item touching Doctrine ORM versions, DB migrations, or platform upgrades now has a hard ordering constraint: this package must land in the same wave as the DBAL 4 migration.
• Platform/PHP support policy: The release adds support for a newer PHP line (listed as "php 5" in the changelog — almost certainly a typo for PHP 8.5; confirm with the maintainer before committing it to a support matrix). This directly informs whether we can adopt that PHP version in our runtime baseline, and whether we hold the upgrade until the package catches up.
• Feature parity assessment: No new product-facing capability in this release. It's a compatibility/maintenance release. Nothing here unlocks a user story on its own; it protects the ones already delivered.
• Framing options: Since Fluent's main value is mapping flexibility (not performance or scale), this release doesn't change the competitive picture — it only changes our maintenance burden.

When to Consider This Package

Adopt when:

• Our Doctrine entity mapping needs to be programmatic — conditional mapping, runtime-generated entity classes, or mapping shared across multiple Laravel apps/packages.
• We want mapping co-located with code and versionable in ways annotations/attributes make awkward (e.g., inheritance and trait-heavy domain models).
• We're already on Doctrine ORM and want a lighter alternative to maintaining bespoke mapping infrastructure.
• New for 3.0.0: we're on, or planning to move to, DBAL 4 — 3.x is the only branch that will take us there. 2.x is now on a legacy dependency line.

Look elsewhere when:

• Our entities use standard Doctrine attributes cleanly — the built-in driver has no dependency cost and no upgrade surface like this.
• We need a stable long-term dependency floor. A 3.0.0 major that jumps DBAL majors in a single PR (with one contributor and a two-line changelog) signals a small maintainer base and infrequent release cadence. Budget for the possibility we absorb DBAL 5 ourselves.
• We're locked to DBAL 3 or an older Laravel/ORM combination — 3.0.0 likely raises the floor, so pin 2.0.1 and accept that we're now on an unmaintained branch.
• We need documented migration guides, deprecation cycles, or LTS-style guarantees. None are present here.

Migration guardrails worth writing into the ticket:

• Verify the exact PHP version actually supported before updating any internal compatibility matrix — the changelog text is ambiguous.
• Check the transitive ORM version required by DBAL 4; a DBAL bump can force an ORM major bump, which is a much larger blast radius than it looks.
• Run the full mapping test suite against a staging database, not just unit tests — DBAL 4 removed APIs that mapping drivers sometimes touch at runtime.

How to Pitch It (Stakeholders)

For executives: This is a maintenance release, not a feature release. The package we use for code-based database mapping has shipped version 3.0.0, which upgrades it to the current major version of Doctrine's database abstraction layer and adds support for a newer PHP version. There is no new customer-facing capability and no change to our product surface. The decision it creates is a scheduling one: we should upgrade, because staying on 2.x leaves us on a dependency line the maintainer has moved past, but the upgrade is a breaking dependency change and needs to be planned alongside our broader Doctrine/PHP platform work rather than slipped into a routine sprint.

For engineering: 3.0.0 is a single-change major — DBAL 4 compatibility plus newer PHP support. Treat it as a breaking change: confirm the actual PHP version supported (the changelog says "php 5", which is almost certainly a typo), confirm which Doctrine ORM major DBAL 4 pulls in, and validate mapping behaviour against a real database in staging rather than relying on unit tests. Also assess maintainer risk: one contributor, no migration guide, no deprecation path. If Fluent is load-bearing for our domain model, we should have a fallback plan to move to native Doctrine attributes or vendor the mapping driver.

Recommendation: Upgrade on the platform-upgrade track, not independently. Pin 2.0.1 only if a blocking incompatibility emerges. Re-evaluate this package's strategic fit at the next major — a third consecutive dependency-major bump with no deprecation cycle would be the signal to migrate off.