Eloquentity Laravel Package

Product Decisions This Supports

• Build vs. buy for domain/entity mapping: If your roadmap includes separating domain entities from Eloquent persistence (hexagonal/ports-and-adapters, DDD-lite, or a modular monolith), this package is a candidate to replace hand-rolled mapping code. The decision it informs is "do we write and maintain our own model↔entity layer, or adopt a small library?"
• Architecture standardization: Choosing whether to standardize how product teams expose persistence models to the rest of the application. Relevant when multiple squads are each inventing their own mapping conventions.
• Testability investment: Release 0.5.3 removes final from the Eloquentity class specifically so it can be mocked. That is a direct signal the package is intended to sit at a seam that teams unit-test in isolation — the kind of decision that affects your testing strategy and CI ergonomics, not just runtime behavior.
• Migration/refactor scoping: Adopting it now means committing to a pre-1.0 API surface. That is a roadmap input: any team adopting it should budget for upgrade work at each minor release, and the decision of when to adopt (now vs. after 1.0) is itself a scheduling call.
• Risk register entry: Introduces a third-party dependency in a core layer (persistence↔domain boundary). Worth a named owner, a version pin, and an exit plan.

When to Consider This Package

Consider it when:

• You are on Laravel and have (or want) a domain layer distinct from Eloquent models — the package's whole premise is entity abstraction over Eloquent.
• Your team writes unit tests around persistence-adjacent classes and needs those collaborators to be mockable. 0.5.3 explicitly optimizes for this; if mocking these classes is part of your test style, the release removes a real friction point.
• You want a small, focused dependency rather than a heavyweight framework — the class surface appears narrow and the maintainer is responsive to testability concerns.
• You are comfortable with pre-1.0 dependencies in non-critical paths, pinned to exact versions and ideally wrapped behind your own thin adapter so a future swap is cheap.

Look elsewhere when:

• You need semver stability guarantees and long-term support. At 0.5.x, breaking changes between minors are expected by convention. If the dependency sits in a regulated or long-lived product path, wait for 1.0 or vendor it.
• The mapping can be done natively with Eloquent resources, casts, and value objects at lower total cost. Adding a dependency to save a small amount of boilerplate is a net loss.
• You require multiple maintainers / commercial support / security SLAs.
• Your organization has a policy against production code being shaped by test-mocking convenience — removing final widens the extension surface and slightly weakens encapsulation. That is a reasonable trade, but it is a trade, and some architects will want to review it.

How to Pitch It (Stakeholders)

For executives (30 seconds): This is a small, single-purpose Laravel library that keeps database code out of our business logic — the same separation that makes systems cheaper to change later. The latest release (0.5.3) is a one-line quality-of-life change that makes the library easier to unit-test; it introduces no new features and no breaking changes. It is not a platform bet: it is a narrow utility, currently pre-1.0, so we would adopt it in one team, pin the version, and keep it behind our own interface so we can walk away cheaply. Recommended position: pilot, don't standardize.

For engineering leads: 0.5.3 drops the final keyword from Eloquentity so it can be mocked in unit tests. Two readings matter here. First, the positive: the maintainer is treating testability as a first-class concern, which is a good cultural signal from a small project. Second, the caveat: enabling mocking of a class is often a hint that the class is being used as a collaborator in tests rather than as pure data — worth a short design review of how we'd actually use it before adopting. final removal is non-breaking for consumers and does not alter behavior; it only widens what subclasses and test doubles can do. Low risk, low blast radius.

For the engineering team doing the evaluation: Pin to 0.5.* or exact-version. Write one adapter/facade in our codebase so no application code imports the package directly. Add a test that exercises the mock path so a future re-finalization upstream fails loudly in CI rather than silently. Re-evaluate at the package's 1.0, or if it goes 90 days without a release while we depend on it.