Getting Started

Install the package with Composer. Laravel package auto-discovery should register the service provider; verify with php artisan about or by resolving IdentityManager from the container.
Look first at the package README and the IdentityManager class. The main entry point is the identity manager itself, which is typically injected into repositories, services, or controllers.
Start with a single read path: resolve IdentityManager, load the same record twice, and confirm both lookups return the same object instance (===). Then call IdentityManager::flushIdentities() and repeat the lookup to confirm a fresh instance is returned.
In v1.1.0, flushIdentities() is the first lifecycle method to learn. Use it at the end of any request, job, or command that should not share identity state with the next unit of work.

Implementation Patterns

Request-scoped usage: Let Laravel’s container provide IdentityManager to your repositories or query services. The identity map keeps repeated lookups consistent within a single request.
Queue workers: Call flushIdentities() in a finally block after each job. Long-running workers otherwise accumulate identity state across jobs, producing stale models or unexpected memory growth.
Laravel Octane / long-running servers: Flush at the end of each request, for example from middleware’s terminate() method or an Octane request-terminated listener. This mirrors the package’s intent for flushIdentities().
Console commands: Flush inside the loop when processing many records, especially if the command runs for minutes or hours.
Tests: Call flushIdentities() in setUp() or tearDown() so identity state does not leak between test cases. Pair this with RefreshDatabase when using a database.
Bulk writes: After Model::query()->update(), delete(), or raw DB::table() writes, flush the identity map. Direct database changes bypass the manager and leave cached identities stale.
Testbench alignment: v1.1.0 fixes orchestra/testbench to match the Laravel version. Keep the package’s testbench constraint aligned with your application’s Laravel version when writing package-level or integration tests.

Stale identities after raw queries: The identity map only knows about objects it has already seen. Any update performed outside the manager—raw SQL, DB::table(), another connection—can leave an old instance in memory. Flush after such operations.
Do not flush mid-unit-of-work: If your business logic depends on receiving the same instance for the same ID, flushing partway through can break === comparisons and object identity assumptions.
Transactions: If a transaction rolls back, identities created or modified during that transaction may no longer reflect the database. Flush after rollback rather than reusing the map.
Memory growth: The new flushIdentities() method is the primary defence against unbounded identity maps in queue workers, Octane, and long-running commands. Treat it as required lifecycle hygiene, not an optional cleanup.
Version alignment: The testbench fix in v1.1.0 is maintenance, but it signals that the package tracks Laravel versions closely. When upgrading Laravel, upgrade this package and its testbench dependency together.
Debugging identity issues: Use === assertions to prove whether two lookups share an instance. If a model appears stale, flush first, then re-query before investigating deeper.
Extension points: If your application wraps the manager in a repository or service layer, expose a single flush() method there so workers and tests do not need to know about IdentityManager directly.