README

Subscribe to individual Eloquent records and receive in-panel Filament notifications whenever they change — with the actor (who) and a field-level diff (what). Watches can carry conditions ("only if status changes", "only if amount > 10K"), can be paused, and live on a personal My Watches page scoped to the authenticated user. Every fan-out is also persisted to a permanent event log, so users can review the full change history even after dismissing notifications.

Highlights

• One-click Watch / Unwatch actions for any Filament Resource record.
• Conditions DSL — JSON rules with changed, =, !=, >, <, >=, <=, contains. ANDed. Empty = notify on any change.
• In-panel notifications delivered through Filament's built-in databaseNotifications() channel — they appear in the bell dropdown.
• Persistent event history — every fan-out writes a WatchEvent row keeping the actor + diff, so users can see what they missed even after clearing notifications.
• My Watches page — auth-scoped, shows event count, supports pause / resume / unwatch / history.
• Per-action permission gates via ->can() (boolean or closure).
• Curated field selector — the condition modal renders a Select populated from a getWatchableFields() hook (auto-introspected by default).
• Actor capture for queues / commands through WatchEngine::actingAs($user, fn () => …).
• Extensible via the RecordWatchedChange Laravel event for email / Slack / audit pipelines.

Requirements

• PHP 8.2+
• Laravel 11+ / Laravel 13
• Filament v4+
• A panel with ->databaseNotifications() enabled (the package writes to Filament's database notifications channel)

Installation

The package is path-linked inside this monorepo. From the project root:

composer require wezlo/filament-record-watcher
php artisan migrate

The migrate step creates two tables: watches and watch_events.

Tailwind v4 — register the package's views

The package ships a Blade view (the History modal) that uses Tailwind utility classes. Tailwind v4 only scans paths it has been told about, so you must add an @source directive to your panel's theme CSS file (typically resources/css/filament/admin/theme.css):

@source '../../../../vendor/wezlo/filament-record-watcher/resources/views/**/*';

After editing the theme, rebuild your assets (npm run build or npm run dev). Without this line the History modal will render unstyled.

Register the plugin on each panel where you want the My Watches page:

use Wezlo\FilamentRecordWatcher\FilamentRecordWatcherPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->databaseNotifications() // required — watchers receive db notifications
        ->plugins([
            FilamentRecordWatcherPlugin::make(),
        ]);
}

Make a model watchable

Add the HasWatchers trait to any Eloquent model:

use Wezlo\FilamentRecordWatcher\Concerns\HasWatchers;

class Order extends Model
{
    use HasWatchers;
}

You can now:

$order->watchFor($user);                                  // subscribe with no conditions
$order->watchFor($user, [                                 // subscribe with rules
    ['field' => 'status', 'operator' => 'changed', 'value' => null],
    ['field' => 'amount', 'operator' => '>',       'value' => 10_000],
]);

$order->isWatchedBy($user);    // bool
$order->watches;               // MorphMany of Watch rows
$order->watchers();            // collection of distinct subscribed users

$order->unwatchFor($user);     // delete the user's subscription (cascades to events)

$order->update(['status' => 'paid']);   // → fans out notifications + events to all matching watchers

watchFor() is idempotent — calling it twice for the same (record, user) pair updates the existing row instead of creating a duplicate (enforced by a unique index).

Curating which fields users can build conditions on

The Field input in the condition modal is rendered as a searchable Select, populated from getWatchableFields(). The trait's default introspects the model's table and returns every column minus the primary key, deleted_at, and any plugin-level ignored columns (default updated_at, created_at).

Override the method on your model to expose a curated list with friendlier semantics:

class Order extends Model
{
    use HasWatchers;

    public function getWatchableFields(): array
    {
        return ['status', 'total', 'client_name', 'address'];
    }
}

Filament integration — WatchAction / UnwatchAction

Drop the actions into any Resource that uses a watchable model. They are two separate actions:

• WatchAction — always visible. Label flips between "Watch" and "Edit watch" depending on whether the current user is already subscribed. Opens a modal with a Repeater of condition rows.
• UnwatchAction — visible only when the current user is already subscribed. One-click confirmation modal.

use Filament\Actions\EditAction;
use Filament\Actions\ViewAction;
use Wezlo\FilamentRecordWatcher\Actions\UnwatchAction;
use Wezlo\FilamentRecordWatcher\Actions\WatchAction;

public static function table(Table $table): Table
{
    return $table
        ->columns([
            TextColumn::make('reference'),
            TextColumn::make('status')->badge(),
        ])
        ->recordActions([
            ViewAction::make(),
            EditAction::make(),
            WatchAction::make(),
            UnwatchAction::make(),
        ]);
}

Both actions also work in page header arrays (headerActions()) on view / edit pages.

Permissions

Both actions expose a ->can() method that accepts a boolean or a closure receiving (Model $record, ?Authenticatable $user) and returning bool. Returning false hides the action for that user / row. The check is ANDed with the action's built-in visibility rules.

WatchAction::make()
    ->can(fn (Order $record, ?Authenticatable $user) => $user?->can('view', $record) ?? false),

UnwatchAction::make()
    ->can(fn (Order $record) => auth()->user()->hasPermissionTo('manage-watches')),

Conditions DSL

Conditions are stored as a JSON array of rules. Empty / null conditions are fail-open — every non-ignored change notifies. Multiple rules are ANDed together.

[
  {"field": "status", "operator": "changed", "value": null},
  {"field": "amount", "operator": ">",       "value": 10000}
]

The Repeater in WatchAction's modal builds this JSON for end users — they pick a field, an operator, and (optionally) a value, then save.

"My Watches" page

The plugin registers a custom Filament Page at /{panel}/my-watches. It's auth-scoped at the query level — users only ever see their own watches.

Columns: model type, record id, conditions ("Any change" or "N rule(s)"), event count badge, paused indicator, watching since.

Row actions:

• History — opens a modal listing every recorded change event for this watch (timestamp, actor name, per-field old → new diff). Survives notification cleanup. Limited to the latest 100 events per click.
• Pause — sets paused_at. Paused watches stop receiving notifications without losing their conditions.
• Resume — clears paused_at.
• Unwatch — deletes the row (and its event history via cascade).

Disable the page from a specific panel:

FilamentRecordWatcherPlugin::make()->registerMyWatchesPage(false)

Or change its navigation:

FilamentRecordWatcherPlugin::make()
    ->navigationGroup('Notifications')
    ->navigationIcon('heroicon-o-bell-alert')

Persistent event history

Notifications can be dismissed, cleared, or simply missed. To make sure users never lose track of changes, every successful fan-out also persists a row in the watch_events table. The history retains the actor and the full field-level diff and is exposed on the My Watches page through the History action.

$watch->events;                                     // HasMany WatchEvent, latest first
$watch->events()->latest()->limit(50)->get();
$watch->events->first()->actor;                     // morphTo — the user who made the change
$watch->events->first()->diff;                      // ['status' => ['old' => 'pending', 'new' => 'paid'], ...]
$watch->events->first()->created_at;

Schema:

Indexed (watch_id, created_at) for fast per-watch history queries. Unwatching cascades — deleting a watch removes its event log automatically.

Actor capture (queues, jobs, commands)

By default, WatchEngine reads auth()->user() to attribute the change. In a queued job, scheduled command, or any context where there is no authenticated user, wrap the write with actingAs():

use Wezlo\FilamentRecordWatcher\Services\WatchEngine;

WatchEngine::actingAs($user, function () use ($order): void {
    $order->update(['status' => 'paid']);
});

The actor is included in the notification body (By {name}), persisted on the WatchEvent row, and dispatched on the event payload.

Self-notify is suppressed

By design, the engine does not notify the actor on their own changes. If user A is watching an order and user A edits it, no notification is delivered (otherwise watching anything you ever touched would spam your bell). The event is also not recorded for the actor's own watches. To verify the system end-to-end, log in as a second user and edit a record the first user is watching.

Events

Every notification fan-out also dispatches a plain Laravel event:

Wezlo\FilamentRecordWatcher\Events\RecordWatchedChange

The event carries the Watch model, the changed Model, the diff array, and the ?Authenticatable $actor. Subscribe to it for email / Slack delivery, audit logging, analytics, or anything else you need beyond the in-panel notification.

use Illuminate\Support\Facades\Event;
use Wezlo\FilamentRecordWatcher\Events\RecordWatchedChange;

Event::listen(function (RecordWatchedChange $event): void {
    // $event->watch, $event->record, $event->diff, $event->actor
});

How change detection works

HasWatchers::bootHasWatchers() registers a static updated model hook that:

1. Builds a field-level diff with DiffBuilder::build($model, $ignored) using the model's getOriginal() + getChanges().
2. Skips ignored columns (updated_at, created_at by default — configurable).
3. If the filtered diff is non-empty, calls WatchEngine::fanOut($model, $diff).

WatchEngine::fanOut():

1. Eager-loads $model->watches()->active()->with('user') (active = paused_at IS NULL).
2. Skips the actor's own watch.
3. For each remaining watch, evaluates conditions via ConditionEvaluator::passes().
4. For each passing watch: persists a WatchEvent, sends a Filament database notification, dispatches RecordWatchedChange.

Database schema

watches

Indexes:

• Unique (watchable_type, watchable_id, user_id) — one watch per user per record.
• (user_id, paused_at) — fast lookup for the My Watches page.

watch_events

See the Persistent event history section above.

Configuration reference

Publish with php artisan vendor:publish --tag="filament-record-watcher-config".

You can also configure most of these fluently on the plugin (->ignoredColumns([...]), ->navigationGroup(...), ->navigationIcon(...), ->userModel(...), ->registerMyWatchesPage(false)) — the plugin values win over config values when both are set.

Low-level service API

use Wezlo\FilamentRecordWatcher\Services\WatchEngine;
use Wezlo\FilamentRecordWatcher\Services\ConditionEvaluator;

// Manually fan out (rarely needed — the observer handles this for you)
app(WatchEngine::class)->fanOut($order, [
    'status' => ['old' => 'pending', 'new' => 'paid'],
]);

// Evaluate a rule set against a model + diff
$passes = app(ConditionEvaluator::class)->passes($order, $diff, $watch->conditions);

// Run a write under an explicit actor (queues, console, system jobs)
WatchEngine::actingAs($systemUser, fn () => $order->update(['status' => 'paid']));

The engine performs no authorization of its own — it's a low-level primitive. Enforce permissions at the caller (action, job, command) before invoking it.

Translations

The package ships English translations under filament-record-watcher::watcher.*. Every user-visible string — action labels, modal headings, notifications, table columns, page title, history modal — is routed through __(). Add additional locales by publishing:

php artisan vendor:publish --tag="filament-record-watcher-translations"

Testing

The package is exercised by 20 Pest tests covering the condition evaluator, the trait surface (watchFor / unwatchFor / getWatchableFields), the observer + engine notification path, the persistent event log (survives notification deletion), the diff builder's ignored-columns behaviour, and the auth-scoped My Watches page. Run them from the host app:

php artisan test --compact tests/Feature/FilamentRecordWatcher

License

MIT.