Add cancel Feature to Deferred Functions

[rbadillap]

Hello everybody and Laravel team.

With the announcement of the new helper defer() and with the spirit to contribute with something valuable to this community, I was checking the source code and noticed the ability to specify a name of the deferred callback so it can be cancelled later. However, I was unable to find where this actually can be cancelled.

Ignoring whether this action is already implemented or not, I think it's valuable to have this ability next to the helper.

Proposed change

Add the ability to cancel deferred callbacks before they are executed. This can be achieved in two ways:

Option 1: Cancelling by name

defer(fn() => performTask(), 'task-name');
// Later...
defer()->cancel('task-name');

Option 2: Cancelling directly

$task = defer(fn() => performTask());
// Later...
$task->cancel();

Implementation Details

I already have this done in my local environment, and would like to share with you my approach.

1. Add a cancel() method to DeferredCallback class.

protected bool $cancelled = false;

public function cancel(): self
{
    $this->cancelled = true;

    return $this;
}

2. Add a cancel($name) method to DeferredCallbackCollection class

public function cancel(string $name): void
{
    foreach ($this->callbacks as $callback) {
        if ($callback->name === $name) {
            $callback->cancel();
            break;
        }
    }
}

3. Update invokeWhen() in DeferredCallbackCollection to skip cancelled callbacks

public function invokeWhen(?Closure $when = null): void
{
   // ...
  if (! $callback->isCancelled() && $when($callback)) {
      rescue($callback);
  }
}

Note

With this approach, no changes are required to the defer() helper function 🎉🥳🎊

Other additions

I also prepared a test suite to cover various scenarios:

• Cancelling by name and directly
• Attempting to cancel non-existent callbacks
• Ensuring cancelled callbacks are not executed
• Verifying normal operation after cancellation

Finally, I also made changes in the documentation to highlight this feature.

Realistic use case

Please consider this as a simple example, cancelling a defer method can be useful in many ways

public function bookRoom(Request $request)
{
    // check availability and lock the room temporarily
    $room = Room::findOrFail($request->room_id);
    $room->lockForBooking();

    try {
        // process the payment
        $payment = $this->processPayment($request->payment_details);

        // confirm the booking
        $booking = Booking::create([
            'user_id' => $request->user()->id,
            'room_id' => $room->id,
            'payment_id' => $payment->id,
            // ... other
        ]);

        // post-response methods
        defer(fn() => Mail::to($request->user())->send(new BookingConfirmation($booking)), 'send_confirmation_email');
        defer(fn() => $this->updateRoomInventory($room), 'update_inventory');
        defer(fn() => $this->logTransaction($booking), 'log_transaction');

        return response()->json(['status' => 'success', 'booking_id' => $booking->id]);
    } catch (PaymentFailedException $e) {
        // Payment failed, let's cancel all defers except log_transaction
        defer()->cancel('send_confirmation_email');
        defer()->cancel('update_inventory');

        // unlock the room
        $room->unlockFromBooking();

        return response()->json(['status' => 'error', 'message' => 'Payment failed'], 400);
    }
}

Pull Request: #52816

Thanks,
Ronny

[rbadillap]

The PR is ready for review.

Tests

[rbadillap]

Closing this due a final resolution. Using forget may solve this challenge.