In Laravel, how do you acquire a Cache::lock() in a controller and release it from the queued job it dispatches, using owner() and restoreLock()?

## The scenario A customer clicks **Generate August statement**. The controller should refuse a second click while the first render is running, but the render itself happens later in a queue worker. So the lock is **acquired in one process** (the web request) and must be **released in another** (the worker), possibly on a different server. Laravel supports this with the lock's **owner token**. ## How owner tokens make this work - Every lock object has an owner string. `Cache::lock($name, $seconds)` generates a random one unless you pass a third argument; `$lock->owner()` returns it. - The store records that owner next to the lock name (a `cache_locks` row on the database store, the key's value on Redis). - `release()` deletes the stored lock only when the stored owner equals the object's owner. - `Cache::restoreLock($name, $owner)` builds a new lock object with the **same name and owner**, without trying to acquire anything. Its `release()` therefore passes the owner check. ## The code, end to end 1. The controller builds the lock name from the account and month and calls `get()`. 2. If `get()` returns `false`, respond with a message (for example a 409 or a redirect with a flash) instead of dispatching. 3. If it returns `true`, dispatch the job with `$lock->owner()` as a constructor argument. The owner is a plain string, so it serializes with the job payload. 4. The job renders the statement and, in `finally`, calls `Cache::restoreLock($name, $this->owner)->release()`. ```php // Controller $lock = Cache::lock("statement:{$account->id}:{$month}", 600); if (! $lock->get()) { return back()->with('status', 'This statement is already being generated.'); } GenerateStatement::dispatch($account, $month, $lock->owner()); ``` ## Failure paths to design for - **The job throws.** Without `finally` (or a `failed()` method that restores and releases), the lock stays until its 600-second lifetime ends, and the customer cannot retry. - **The job never runs** (queue backlog, worker down). The lock's lifetime is the only thing that frees it, so size it for realistic queue delay plus render time, not for render time alone. - **The lifetime ends before the job finishes.** Another click can then acquire the lock and dispatch a second job. When the first job finishes, its owner-checked `release()` returns `false` and leaves the newer lock alone. - **Wrong store.** `restoreLock()` must be called on the same store that issued the lock. If the controller used `Cache::store('redis')->lock(...)`, the job needs `Cache::store('redis')->restoreLock(...)`. - **Manual clean-up.** After a crash, an operator can run `Cache::lock($name)->forceRelease()` to delete the lock regardless of owner. ## The `refresh()` trap on restored locks The built-in stores implement `restoreLock()` as `lock($name, 0, $owner)`, so the restored object's own lifetime is **0**. Calling `refresh()` with no argument re-applies that 0: | Store | `refresh()` on a restored lock with no seconds | |---|---| | Redis | removes the expiry entirely (the lock no longer expires) | | Database | sets expiry to the store's `lock_timeout`, 86400 s by default | Pass the intended lifetime explicitly: `Cache::restoreLock($name, $this->owner)->refresh(600)`. ## When to prefer something else This cross-process pattern is for locks whose scope is "from the click until the job ends". Laravel also ships job-level uniqueness and job middleware for overlapping jobs; those are separate features with their own rules, and the raw lock remains the tool when the lock must start in the web request. ## Choosing your own owner `Cache::lock($name, $seconds, $owner)` accepts an owner as its third argument. Supplying a meaningful value — for example an identifier of the statement request stored in the database — can make logs clearer and lets any process that knows that identifier restore the lock without passing a random token around. The trade-off is that a predictable owner is easier to reuse by mistake: two requests that compute the same owner would both pass the owner check. Random owners, the default, avoid that, so only choose your own when the value is genuinely unique per acquisition.