Getting Started

Minimal Setup

Installation

composer require noxoua/filament-activity-log
php artisan vendor:publish --provider="Noxoua\FilamentActivityLog\FilamentActivityLogServiceProvider" --tag="filament-activity-log-config"
php artisan migrate

Ensure spatie/laravel-activitylog is installed (this package extends it).

Configure Activity Log Model In config/filament-activity-log.php, set your ActivityLog model (default: Spatie\Activitylog\Models\Activity).
First Use Case: Log Model Events Add the HasActivityLog trait to your Eloquent model:
```
use Noxoua\FilamentActivityLog\Traits\HasActivityLog;

class Post extends Model
{
    use HasActivityLog;
}
```
- Logs will now auto-capture create, update, delete, and restore actions.
Access the Logs Panel The package adds a "Activity Log" widget to Filament’s dashboard by default. Click to view logs.

Implementation Patterns

Core Workflows

Logging Custom Actions Extend logging beyond CRUD:

use Noxoua\FilamentActivityLog\Facades\FilamentActivityLog;

FilamentActivityLog::log(
    model: $user,
    action: 'flagged',
    properties: ['reason' => 'Spam'],
    description: 'User flagged for spam'
);

Filtering Logs in Filament Override the default log table with a custom query:

// In a Filament resource or widget
use Noxoua\FilamentActivityLog\Widgets\ActivityLogWidget;

ActivityLogWidget::make()
    ->query(fn ($query) => $query->where('properties->status', 'published')),

Integrating with Filament Policies Restrict log visibility by user roles:

// In a Filament policy
public function viewActivityLogs(User $user): bool
{
    return $user->can('view_activity_logs');
}

Batch Processing Logs Use the ActivityLog model directly for bulk operations:

$logs = ActivityLog::where('log_name', 'posts')
    ->where('properties->action', 'update')
    ->get();

Advanced Patterns

Customizing Log Descriptions Override the default description generator:

// In your model
public function getActivitylogDescriptionForEvent(string $eventName): ?string
{
    return match ($eventName) {
        'created' => "{$this->title} was created by {$this->creator->name}",
        default => parent::getActivitylogDescriptionForEvent($eventName),
    };
}

Adding Logs to Filament Actions Log actions triggered via Filament buttons:

use Noxoua\FilamentActivityLog\Facades\FilamentActivityLog;

$record->update([
    'status' => 'published',
]);

FilamentActivityLog::log(
    model: $record,
    action: 'publish',
    description: "Published {$record->title}"
);

Real-Time Log Updates Use Laravel Echo/Pusher to notify admins of critical log events:

// In your event listener
event(new ActivityLogged($activityLog));
// Broadcast via Echo/Pusher

Exporting Logs Add a Filament action to export logs as CSV/Excel:

use Filament\Tables\Actions\Action;

Action::make('export')
    ->label('Export Logs')
    ->action(fn () => LogExporter::export(ActivityLog::all())),

Gotchas and Tips

Common Pitfalls

Missing Migrations
- Issue: Logs don’t appear after setup.
- Fix: Run php artisan migrate to create the activity_logs table.
- Tip: Verify the log_name column exists (default: spatie/laravel-activitylog uses log_name).

Incorrect Model Binding

Issue: Logs show [object] instead of model data.

Fix: Ensure your model uses HasActivityLog trait and has a getActivitylogOptions() method if customizing:

public function getActivitylogOptions(): array
{
    return [
        'log_only' => ['created_at', 'updated_at'], // Exclude fields
        'log_name' => 'custom_posts',
    ];
}

Permission Denied
- Issue: Filament widget shows "403 Forbidden".
- Fix: Register the widget in a policy or gate:
```
Gate::define('view-activity-logs', fn () => auth()->user()->can('view_activity_logs'));
```

Performance with Large Logs

Issue: Slow queries when fetching logs.

Fix: Add indexes to log_name, properties, and created_at:

Schema::table('activity_logs', function (Blueprint $table) {
    $table->index('log_name');
    $table->index('created_at');
});

Tip: Use cursor() for pagination in Filament tables:
```
ActivityLog::query()->cursor()->paginate(20);
```

Debugging Tips

Log Not Triggering?
- Check config/filament-activity-log.php for enabled set to true.
- Verify spatie/laravel-activitylog is installed and configured.
Properties Not Serializing
- Issue: properties column shows null or malformed JSON.
- Fix: Ensure properties are JSON-serializable (no resources, closures, or circular references).
Custom Logs Overwritten
- Issue: Default CRUD logs override custom logs.
- Fix: Use log_only in getActivitylogOptions() to exclude default events:
```
'log_only' => ['custom_action'], // Only log this
```

Extension Points

Custom Log Views Override the default Filament widget:

// In a Filament plugin
FilamentActivityLogServiceProvider::macro('widget', fn () => CustomActivityLogWidget::make());

Add Logs to Filament Notifications Extend the ActivityLogged event:

event(new ActivityLogged($activityLog));
// Listen for it in a service provider
ActivityLogged::listen(fn ($event) => notify(new LogNotification($event->activityLog)));

Webhook Triggers Dispatch logs to external services:

// In ActivityLogged listener
Http::post('https://your-webhook.com/logs', [
    'log' => $event->activityLog->toArray(),
]);

Soft-Deletes in Logs Configure spatie/laravel-activitylog to log soft deletes:
```
// In config/activitylog.php
'should_log_soft_deletes' => true,
```

Pro Tips

Audit Trail for Filament Actions: Log all Filament form submissions:

use Noxoua\FilamentActivityLog\Facades\FilamentActivityLog;

$form->saved(function (Model $record) {
    FilamentActivityLog::log(
        model: $record,
        action: 'filament_update',
        properties: ['field' => 'title', 'old' => $oldValue, 'new' => $newValue],
    );
});

Anonymize Sensitive Data:

// In ActivityLog model observer
$activityLog->properties = collect($activityLog->properties)
    ->map(fn ($value, $key) => Str::contains($key, 'password') ? '[redacted]' : $value)
    ->toArray();
$activityLog->save();

Filament Activity Log Laravel Package