Eloquence Laravel Package

Product Decisions This Supports

• Long-running worker and Octane readiness: IdentityManager::flushIdentities() gives the application an explicit reset point for the identity map. This is the difference between "works in a request lifecycle" and "safe to run in a queue worker or persistent process," and it directly feeds the roadmap decision on whether the service is Octane-compatible.
• Test suite hygiene: the same method makes identity-map state resettable between tests, reducing order-dependent or flaky test failures — a build-vs-buy argument for adopting the package rather than hand-rolling identity caching.
• Memory and correctness trade-off: an identity map is a caching decision. Being able to flush on demand means the PM can ship a bounded-memory default (flush per job/batch) instead of accepting unbounded growth, or scoping the feature to short-lived request paths only.
• Data-consistency use cases: identity mapping is most valuable where the same entity is read repeatedly within one unit of work (reporting loops, import/export jobs, batch processing). This release strengthens the case for those features without new product surface area.
• Maintenance signal: the testbench version alignment indicates active compatibility tracking with Laravel releases — relevant to support-window and upgrade-cost estimates.

When to Consider This Package

Adopt when:

• You have repeated reads of the same model/entity inside a single logical operation and observe redundant queries or inconsistent in-memory instances.
• You run queue workers, Laravel Octane, or any process that survives beyond one request and therefore needs a deterministic reset (flushIdentities()).
• Your team already accepts identity-map semantics and understands that a flush is required after bulk writes or external mutations, or the map can serve stale objects.

Look elsewhere when:

• The application is a conventional request-per-process CRUD app with low read repetition — the map adds a stale-data failure mode for little gain.
• The team cannot commit to calling flushIdentities() at the right boundaries (job start/end, after raw queries, after bulk updates). Without that discipline, this becomes a data-correctness risk rather than a performance win.
• You need framework-level, out-of-the-box query-result caching — Laravel's cache or remember() is a better-understood buy.
• Note the release provenance: v1.1.0 is dated 2020 and the notes are sparse. Verify current Laravel compatibility and maintenance activity before committing; that check belongs in the adoption decision, not after.

How to Pitch It (Stakeholders)

To executives: this is a small, low-cost dependency that removes duplicated database reads inside batch jobs and makes our queue/Octane workloads safe to run in long-lived processes. The 1.1.0 release adds the missing piece — an explicit reset — which converts it from a convenience into something we can responsibly put in production. Cost is a dependency plus a code-review rule; benefit is fewer queries and more predictable memory in background processing.

To engineering: IdentityManager::flushIdentities() clears the identity map on demand. Use it at job boundaries, in test setUp/tearDown, and after any bulk write or raw query that bypasses the mapper. The testbench version fix is housekeeping — it keeps our test harness aligned with the Laravel version we pin. Treat flush placement as part of the definition of done for any feature that touches mapped entities; unflushed state is a stale-read bug waiting to happen.