Download the PHP package splitstack/laravel-nudge without Composer

Laravel Nudge

Give notifications a lifecycle. A notification declares the action it is waiting on; when that action runs anywhere in your application, the notification resolves itself — no manual wiring required.

→ See it in action

Installation

Publish and run the migration:

The migration adds a resolved_at column to your notifications table. If the table does not exist yet, it creates it.

Concept

A notification is not just a message — it is a pending state tied to an expected future action.

The controller, the webhook handler, and the notification have no knowledge of each other.

Actions

There are two ways to make an action class resolvable, depending on whether it already exists or is being written from scratch.

New action classes — extend NudgeAction

If you are writing an action class from scratch, extend NudgeAction. Implement your logic in a protected nudge() method (convention) or in any method marked #[Nudge] (for a custom name). The handle() entry point, event dispatch, and resolution are all handled for you.

If you prefer a different method name, mark it with #[Nudge]:

Call sites — pick whichever style fits your codebase:

Existing action classes — use the trait

If you have an action class that already exists and already has its own call sites, you do not need to rewrite call sites. (You're free to do so if you want, of course. In that case refer to the "New action classes" section above)

Implement ResolvableAction, add the DispatchesActionExecuted trait, and drop $this->nudge($params) at the point in your method where the action completes. Your call site stays exactly as it was.

You can also dispatch the event manually as an escape hatch — useful for actions you don't own:

Notifications

Extend ActionableNotification and supply the action key either via forAction() at call site or by overriding useActionKey() on the class.

Option A — forAction() at call site (action key decided by the caller):

Option B — useActionKey() on the class (action key baked into the notification):

withData() is optional — omit it if your notification needs no payload beyond the action metadata. If both useActionKey() and forAction() are used, useActionKey() takes precedence.

Param matching

The stored params are matched as a subset of the executed params. This means:

Extra keys in the executed params are ignored. Store only the params that must match.

Deep matching

By default matching is shallow — only top-level keys are compared. Set match_params to 'deep' in config/nudge.php to enable recursive subset matching, useful when your action params contain nested arrays:

Matching is strict (===) at every level regardless of mode, so '5' and 5 are not considered equal.

Querying

Add HasResolvableNotifications to your notifiable model for convenience scopes:

Or query directly on DatabaseNotification:

Migrating an existing notification class

If you already have a notification with a toDatabase() method and you swap extends Notification for extends ActionableNotification, do not keep the toDatabase() override. ActionableNotification::toDatabase() is what injects _action_key and _action_params into the stored payload — overriding it silently strips that metadata and the notification will never resolve.

Replace toDatabase() with withData() instead:

withData() is merged into the final payload by the parent; your data and the action metadata both end up in the database.

Upgrading from < 0.6.0

The old execute() entry point and the requirement to name your handler handle() have been removed in favour of the two-path API above. execute() still works but emits E_USER_DEPRECATED — follow the deprecation message to migrate at your own pace.

Caveats

Avoid sending notifications inside controller methods that can be hit multiple times

Some middleware or frontend patterns cause controller methods to be invoked more than once per user interaction. A well-known case is Inertia.js deferred props: a HandleInertiaRequests middleware that uses Inertia::defer() triggers a second request to the same route, calling the controller twice. If $user->notify(...) is in that controller, the same notification gets stored twice.

The safer placement is inside a dedicated action, a queued job, an observer, or a service — anywhere outside the HTTP layer that can be hit multiple times.

Requirements

• PHP 8.2+
• Laravel 11+