Filament Logger Laravel Package

Getting Started

Pin the major before you install anything. v5.0.0 targets Filament 5 / Livewire 4, Laravel 12–13, PHP 8.2+. The Filament 3 line lives on a separate v3 branch and is not compatible with v5. Commit the lockfile — this package crossed five majors and composer update will happily move you between them.

composer require tomatophp/filament-logger
php artisan filament-logger:install   # publishes config + lang to lang_path(), runs migrations in-process

On a fresh app that's fine. On a shared database, read what the install command is about to run and prefer an explicit php artisan migrate in your deploy pipeline over the in-process shortcut.

Register the plugin on the panel that should expose the log:

// app/Providers/Filament/AdminPanelProvider.php
public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->plugin(\TomatoPHP\FilamentLogger\FilamentLoggerPlugin::make());
}

Where to look first, in order:

1. config/filament-logger.php — the center of gravity. Model/table name, which events are recorded, request filtering. Read this before writing integration code.
2. The published migrations — the real schema. Confirm the columns (causer, subject, event, properties, timestamps) and whether your install is DB-backed in practice, not just per the README.
3. src/ — the FilamentLogger facade (FilamentLogger::log()), the Filament page/resource, and the request listener. In v5 the listener is subscribed directly; the old EventServiceProvider subclass is gone.
4. README screenshots — fastest route to the intended UX before you start customizing filters.

First use case, covering both surfaces. This package does two things and you should validate each separately:

• Activity table: open the log page, have a second user edit a record, confirm the entry lands with the correct causer. Then click Clear Activities and confirm the table actually empties — v5 switched that action from TRUNCATE to DELETE, so re-test it rather than trusting it after an upgrade.
• File log viewer: confirm the Laravel log files render, search filters entries, and download works. That surface is independent of the database and fails for different reasons.

Implementation Patterns

Write through FilamentLogger::log(), never Log::info(). Anything sent to a Laravel log channel will not appear in the activity table. The helper applies causer resolution, properties encoding, and the table's schema expectations consistently. Manual entries always go through it.

Log per model, not globally. Register the observer or trait only on models that matter — invoices, users, roles, settings. A blanket created/updated/deleted hook on every model turns the table into a firehose within a week, and the default unfiltered newest-first view becomes useless long before the table gets slow.

// app/Observers/InvoiceObserver.php
public function updated(Invoice $invoice): void
{
    FilamentLogger::log(
        event: 'updated',
        subject: $invoice,
        properties: [
            'changed'   => array_keys($invoice->getChanges()),
            'tenant_id' => tenant('id'),
            'ip'        => request()->ip(),
        ],
    );
}

Enrich with context at the write site. The Log::withContext() middleware trick does not carry into a DB row. Pass context into the call. Keep properties to scalars and identifiers — it is stored serialized and rendered in a table cell, so prefer recording which attributes changed over the values themselves.

Prune, don't archive. A database-backed log means unbounded growth is your problem now, not logrotate's. Add a Prunable model or a nightly DELETE WHERE created_at < now()->subDays(90), and index created_at plus the causer column if you filter by user often. "Clear Activities" is a human button, not a retention policy — and as a row-by-row DELETE it degrades as the table grows.

Filter noise at the source. v5 tightens exclusion of Livewire 4 update requests, which otherwise bury real edits under a stream of /livewire/update POSTs. If noise persists, fix it in the config's request-filtering keys and the request.livewire flag — not with post-filtering in the UI.

Disable logging inside bulk work. Each activity is an INSERT plus a serialized payload. Imports and queued jobs touching thousands of rows will dominate write time. Wrap them in Model::withoutEvents(...) (or a config toggle) and write one summary entry instead.

Gate the viewer before you deploy. A freshly registered plugin page is typically visible to anyone who can reach the panel, and it exposes other users' activity. Customize it as a normal Filament page: override table filters, add a causer filter backed by your User model, set navigation group/icon, and attach a policy gate.

Multi-panel setups: register the plugin on the admin panel only. Two panels on the same page slug collide; two panels reading the same table is fine.

Don't double-write. spatie/laravel-activitylog and this package overlap heavily. Pick one for a given event set — writing both means two tables to prune and two schemas to keep in sync.

Gotchas and Tips

• The Filament 3 / Filament 5 split is a hard fork. v5.0.0 will not install on Filament 3; the v3 branch is a separate maintenance line with no announced support window. Pin "tomatophp/filament-logger": "^5.0" (or the v3 equivalent) and commit the lock.
• FilamentLogger::log() used to require REDIRECT_STATUS. On nginx and php artisan serve that superglobal is unset, so logging silently broke outside Apache/php-fpm. Fixed in v5.0.0 — below that, expect no-writes in local dev and behind nginx. Verify with a manual FilamentLogger::log() before debugging anything else.
• TRUNCATE inside a MySQL transaction. Pre-5.0.0 "Clear Activities" could fail when wrapped in a transaction; v5 uses DELETE. Any test or wrapper asserting the table is emptied needs re-checking after the upgrade.
• Double-registered email verification listener. v5 removes the EventServiceProvider subclass that subscribed it twice, so verification events no longer duplicate. If you extended that provider to suppress them, your override is gone — move the behaviour to config.
• N+1 on the causer. v5 eager-loads the causer on the table. If you replace the table or add your own causer column, eager-load it yourself (->with('causer')) or you reintroduce the query storm the release just fixed.
• Redact before you write. Model updated events will happily serialize password hashes, API tokens, and PII into properties. Rely on $hidden, and prefer array_keys($model->getChanges()) over values.
• Testing: the package now ships a Pest suite and CI across Laravel 12/13 and PHP 8.3/8.4. In your own tests, assert against the activities table or FilamentLogger calls, not rendered HTML, and use in-memory SQLite so migrations run fast and the table is clean per test.
• Debugging loop: write one activity by hand (FilamentLogger::log(...) in tinker), then refresh the panel page. Row in the table but not on the page → read path (wrong model, filter excluding it, causer not resolving). Row missing from the table → write path (observer not registered, model not opted in, helper failing silently). For the file viewer, failures are almost always path/permission issues, not schema.
• Extension points, in order of safety: config → FilamentLogger::log() calls in your own observers → a custom Filament page subclass → forking. Forking means hand-merging on every release, and with this much Filament 5 / Livewire 4 churn you'll be doing those merges regularly.