Audit Filament Laravel Package

Getting Started

This package is a presentation adapter — it sits on top of a separate audit module and exposes it inside Filament. Treat it as glue, not as a full audit system. The first thing to confirm is what it actually ships: src/, config/, resources/views/, database/migrations/, and a service provider that registers Filament resources, pages, or widgets.

Minimal steps:

1. Install the audit domain module first. audit-filament almost certainly depends on liberusoftware/module-audit (or equivalent) for models, migrations, and the audit-writing service. The adapter has nothing to display without it.

   composer require liberusoftware/module-audit liberusoftware/audit-filament
   

2. Verify Filament is already installed and a panel exists (php artisan filament:install --panels if not). The adapter targets a specific Filament major version — check composer.json constraints before wiring anything.
3. Run migrations and confirm the audit table is populated:

   php artisan migrate
   php artisan tinker
   >>> \LiberuSoftware\Audit\Models\Audit::count();
   

4. Register the plugin/resource in your panel provider. The exact call depends on what the package exposes — look for a Plugin class (->plugin(AuditPlugin::make())) or a Resource auto-discovery path in src/.

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugins([
               \LiberuSoftware\AuditFilament\AuditFilamentPlugin::make(),
           ]);
   }
   

5. First use case: open the admin panel and browse the audit resource — typically a read-only table of audit entries with filters by model, event, user, and timestamp. That table is the product. Everything else is customization.

Where to look first, in order:

• composer.json — Filament and module-audit version constraints (the single most important file here).
• src/*ServiceProvider.php — what gets registered, config keys, publishable assets.
• src/Filament/Resources/ and src/Filament/Widgets/ — the actual UI surface you'll be extending.
• README.md — with 0 stars and NOASSERTION license, docs are likely thin or stale. Read the source.

License note: NOASSERTION means the composer metadata could not be matched to a standard SPDX license. Confirm licensing with the maintainer before production use. This is a real blocker for commercial projects, not a formality.

Implementation Patterns

Because the adapter is thin, most day-to-day work is ordinary Filament resource customization rather than "using the package." Useful patterns:

Register per panel, not globally. Audit logs are usually admin-only. Register the plugin/resource only on your admin panel provider, not on customer-facing panels.

Read-only by design. Audit tables should not be editable. Remove create/edit/delete actions, or the audit module's immutability guarantees are undermined. If the resource ships with mutation actions, override getPages() or the resource's table() to strip them.

Filter and search deliberately. Audit tables grow fast. Wire the table filters to indexed columns (created_at, auditable_type, auditable_id, event, user_id). Add a date-range filter as your first customization — it is the difference between a usable screen and a timeout.

Scope by tenancy/team. If your app uses Filament tenancy, extend the resource's query to constrain audits to the current tenant. Do not rely on the package to do this; verify the generated query in the debug bar.

Compose with the model view. A common pattern is a relation manager or action on your domain resources ("View audit trail") that deep-links into the audit resource filtered by auditable_type/auditable_id. Prefer this over duplicating audit tables per model.

// Example: scoping the audit resource query
public static function getEloquentQuery(): Builder
{
    return parent::getEloquentQuery()
        ->where('tenant_id', Filament::getTenant()?->id)
        ->latest('created_at');
}

Dashboard widget. Audit adapters often ship a "recent activity" widget. Register it via ->widgets([...]) and apply the same tenant scoping — widgets frequently bypass resource-level query scoping.

Extension over fork. Before editing vendor code, check for Filament's standard extension points: configureUsing(), resource subclassing, ->table(fn (Table $table) => ...), and action/column ->visible() callbacks. A presentation adapter should be replaceable by subclassing its resource and pointing the panel at yours.

Testing. Use Filament's testing helpers (livewire(), assertCanSeeTableRecords()) against a seeded audit table. This both validates the adapter and pins its behavior against future package upgrades — important when the dependency has no release cadence you can rely on.

Gotchas and Tips

Version coupling is the top risk. Filament v3 → v4 changed resource namespaces, Table APIs, and page registration. A package with 0 stars, no dependents, and a single maintainer is unlikely to track Filament majors promptly. Pin filament/filament and liberusoftware/audit-filament to known-good versions in composer.json, and test upgrades in isolation.

NOASSERTION license. As above — resolve before shipping. Also check whether module-audit carries a different license.

Missing/dangling dependency. If the package requires module-audit at a specific constraint, a mismatch produces confusing "class not found" errors in the panel, often surfaced as a blank page rather than a stack trace. Check composer why-not liberusoftware/module-audit when the panel breaks.

Config merge quirks. Package configs registered with mergeConfigFrom cannot be overridden by partial publishes — if you publish the config and later upgrade the package, new keys are silently absent. Re-publish or diff against vendor/.../config/.

Performance on large tables. Audit tables are append-only and unbounded. Watch for:

• Missing indexes on auditable_type/auditable_id (the morph pair).
• N+1 loads when rendering the auditable relation or user per row — eager load both.
• count() on paginated tables with expensive filters. Consider pruning or archiving old entries, and document retention policy.

Read-only isn't enforced by the package. Even if the UI hides edit actions, the audit model may still be mass-assignable. Enforce immutability at the model level (guarded attributes, no update/delete) so a rogue resource or console command can't rewrite history.

Panel boot exceptions are opaque. Filament aggregates plugin registration errors; a bad constructor in the adapter often shows as a broken panel with nothing in the log. Wrap plugin registration in a try/catch during development, or run php artisan filament:cache-components / clear caches to surface errors.

No dependents means no community answers. There will be no Stack Overflow results, no issues to search. Budget time for reading the source. Keep a local fork or patch file (composer-patches) ready for small fixes rather than waiting on maintainer response.

Extension points to prefer: subclass the shipped resource and widget rather than publishing/editing views; use configureUsing() for global table tweaks; override getEloquentQuery() for scoping; register actions on your own domain resources for the deep-link pattern. These survive package upgrades far better than vendor edits.

Release date anomaly. The metadata lists a last release in 2026 — treat the versioning signal as unreliable and verify against Packagist and the actual git tags before depending on it.

Recommendation: this is a low-risk presentation layer if the audit domain module is solid, but it is not a package to build core workflows around. Contain it behind your own panel configuration so it can be replaced by a hand-written Filament resource in an afternoon if the package goes stale.