Adds a new withHeartbeat method to LazyCollection, which allows you to run a callback at regular time intervals while the collection is being lazily enumerated:

$collection
    ->withHeartbeat(CarbonInterval::minutes(5), function () {
        // ...
    })
    ->each(function ($item) {
        // ...
    });

Main use case

In long-running tasks such as batch processing reports, you may need to hold a lock to prevent concurrent execution. However, if the code unexpectedly fails to release the lock, you don't want it to persist indefinitely. A common strategy is to acquire a short-lived lock, and then periodically extend it while the task is still running.

Here's an example where we acquire a lock for 5 minutes, then reacquire it every 4 minutes (assuming a report never takes a full minute to generate):

$lock = Cache::lock('generate-reports', CarbonInterval::minutes(5));

$lock->acquire();

Reports::where('status', 'pending')
    ->lazy()
    ->withHeartbeat(CarbonInterval::minutes(4), $lock->reacquire(...))
    ->each($this->generateReport(...));

$lock->release();

Note: the locking logic above is simplified for clarity. It's essentially pseudo-code.