Feature: Pausing and resuming actions

[webard]

Description

This pattern already exists: people build it today on top of halt(). An action checks in before() whether something is satisfied; if not, it mounts an additional action and interrupts itself with halt(). The child modal collects whatever was missing, then removes itself from the stack and calls callMountedAction() back on the parent.

This works, but every retry is a new attempt, not a continuation, from Filament’s perspective, so the whole process runs again. There are three effects that cannot be fixed from the outside:

• Limiter: ->rateLimit(3) effectively gives you one successful flow, because interrupting and resuming each consume one hit. The limiter runs before any hook the author controls.
• beforeFormValidated() and afterFormValidated() run twice. There is no way to prevent them from being called; at best, you can make your own code idempotent, which the documentation does not mention.
• ActionCalling event fires twice, which breaks audit flows based on that event.

There is also an extensibility problem: before() is a single closure, so a plugin cannot hook into it without overwriting the application’s hook. The only non-overridable extension point today is the undocumented ActionCalling event.

What changes

An action can now be paused. A paused action remains mounted together with the data the user has already entered, and the next call is a resume of that action: stages that have already run are not repeated.
Conditions are registered through pauseWhen(). They are evaluated after schema validation and before the before() hook:

Action::make('transferFunds')
    ->schema([
        // ...
    ])
    ->pauseWhen(fn (): bool => ! session()->has('identity_confirmed_at'))
    ->action(function (array $data): void {
        // ...
    })

Conditions accumulate instead of overwriting each other, so a plugin can pause an action without stepping on a condition registered by the application, and vice versa. Alternatively, $action->pause() can be called imperatively from before() or from the action body.

Use cases

• Data freshness. Someone opened an edit form, and the record changed underneath them in the meantime. You pause, show the diff, and let the user decide. Today this cannot be done cleanly: requiresConfirmation() runs before the form, while this is only known after validation.

• Conflict detection: another user has already managed to perform the operation.

• Impact preview: "This operation will affect 1,240 records and delete 3 related invoices. Continue?", calculated on the server after validation.

• Re-authentication before a sensitive operation: password, OTP code.

• Missing data: the action needs a delivery address that the customer does not have. A modal adds it and fills the parent form, and the user does not lose anything they have already entered.

• Limits or billing: "You’re out of credits", top-up modal, resume.

Security

The stage at which the action stopped is stored in #[Locked] public array $pausedMountedActions, so the browser cannot forge it to bypass the limiter or validation hooks.

Pause conditions are recalculated on every call, including on resume. This is intentional: the browser can call callMountedAction() on a paused action at any moment, even after cancelling the child modal, so execution is decided by the conditions, not by saved state.

Backward compatibility

Nothing changes for actions that do not use pausing. One public Livewire property has been added: an empty array until something is paused.

Demo

Working demo: https://github.com/webard/filament-pauseable-otp-demo

git clone -b filament-pauseable-extracted-otp https://github.com/webard/filament.git filament
git clone https://github.com/webard/filament-pauseable-otp-demo.git demo
cd demo && composer setup && php artisan serve

Both clones need to sit next to each other, because the demo points to Filament through relative paths: ../filament/packages/*.

Note: the demo branch merges this PR with #20353, which extracts the multi-factor challenge outside the login page.

Proof of concept

https://github.com/webard/filament-otp-actions

The package adds a requiresOtpConfirmation() macro to actions, which confirms an action using a one-time code from the multi-factor method configured by the user. It is built entirely on the public API introduced by this PR: it registers a condition through pauseWhen(), mounts its own challenge modal, and resumes the action after a valid code.

Note: this package uses functionality from #20353, which extracts the multi-factor challenge outside the login page.

Functional changes

• Code style has been fixed by running the composer cs command.
• Changes have been tested to not break existing functionality.
• Documentation is up-to-date.