## Getting Started

1. **Installation**:
   ```bash
   composer require croustibat/filament-jobs-monitor
   php artisan vendor:publish --tag="filament-jobs-monitor-migrations"
   php artisan migrate

Verify your Filament version matches the package requirements (e.g., v4.x for Filament 5.x).

First Use Case: Dispatch a queued job:
```
MyJob::dispatch();
```
Access the monitor via /admin/queue-monitors (or your configured route). The dashboard will show all jobs (pending, processing, failed) with their status, payload, and execution details.
Quick Configuration: Publish the config file:
```
php artisan vendor:publish --tag="filament-jobs-monitor-config"
```
Update config/filament-jobs-monitor.php to define your queues (e.g., ['default', 'emails']) and enable/disable features like pruning or navigation.

Implementation Patterns

Core Workflow

Job Dispatching: Integrate with existing job dispatch logic. Example:

// In a Filament action or controller
public function exportUsers(Collection $users) {
    UsersExportJob::dispatch($users);
    Notification::make()->success()->send();
}

Monitoring Integration:

Navigation: Register the plugin in AdminPanelProvider:

FilamentJobsMonitorPlugin::make()->enableNavigation();

Conditional Access: Restrict visibility via closures:

FilamentJobsMonitorPlugin::make()
    ->enableNavigation(fn () => auth()->user()->can('view_jobs'))

Multi-Tenancy:

Enable in config:

'tenancy' => [
    'enabled' => true,
    'model' => App\Models\Tenant::class,
    'column' => 'tenant_id',
],

Ensure jobs include a tenantId property (supports int|string):

class TenantJob implements ShouldQueue {
    public function __construct(public string|int $tenantId) {}
}

Customization:

Model Extension: Extend the default model for custom methods:

class CustomQueueMonitor extends \Croustibat\FilamentJobsMonitor\Models\QueueMonitor {
    public function getCustomAttribute() { ... }
}

Update the config to use your model:

'resource' => App\Models\CustomQueueMonitor::class,

Pruning: Automatically purge old jobs via config:

'pruning' => [
    'enabled' => true,
    'retention_days' => 14,
],

Advanced Patterns

Dynamic Queue Filtering: Use the queues config array to dynamically filter monitored queues:
```
'queues' => ['default', 'high-priority'],
```

Action Integration: Trigger jobs from Filament tables/actions:

->bulkActions([
    BulkAction::make('process-batch')
        ->action(function (Collection $records) {
            ProcessBatchJob::dispatch($records->toArray());
        }),
])

Widget Integration: Embed job stats in Filament dashboards:

StatsOverviewWidget::make()
    ->columns(2)
    ->addCard(
        Stat::make('Pending Jobs', $this->getPendingJobCount())
    ),

Gotchas and Tips

Common Pitfalls

Queue Configuration:
- Missing Queues: The package requires explicit queue definitions in config. Omitting queues (e.g., ['default']) will hide their jobs from the monitor.
- Dynamic Queues: If queues are dynamically named (e.g., queue:tenant-{id}), manually add them to the config or extend the QueueMonitor model to handle dynamic scoping.
Multi-Tenancy:
- Payload Serialization: Jobs with tenantId as string (e.g., UUIDs) require the tenant_id column in the queue_monitors table to be string (not unsignedBigInteger). Run:
```
php artisan vendor:publish --tag="filament-jobs-monitor-migrations" --force
php artisan migrate
```
- Backward Compatibility: Existing integer-based tenant_id records remain compatible, but new jobs with string IDs will use the updated format.
Performance:
- Large Payloads: Jobs with large payloads may slow down the monitor. Use ->limit(100) in the resource table to paginate results:
```
public static function table(Table $table): Table {
    return $table->paginate(100);
}
```
- Pruning: Enable pruning to avoid bloat:
```
'pruning' => ['enabled' => true, 'retention_days' => 7],
```
Debugging:
- Missing Jobs: Verify the failed_jobs table is populated (for failed jobs) and that the queue worker is connected to the database.
- Modal Crashes: If clicking "Details" fails with exception_message errors, ensure the QueueMonitor model is properly extended and the action closure uses $record (not $queueMonitor):
```
->action('details')
    ->modalContent(fn ($record) => view('filament-jobs-monitor::details', ['record' => $record]))
```
Filament Version Mismatches:
- Upgrade Issues: When upgrading Filament versions, check the UPGRADE.md for breaking changes (e.g., Form → Schema in v4).
- Plugin Registration: For Filament Panels, ensure the plugin is registered in the panel provider:
```
->plugins([FilamentJobsMonitorPlugin::make()])
```

Pro Tips

Custom Columns: Add custom columns to the table by extending the resource:

public static function table(Table $table): Table {
    return $table
        ->addColumns([
            Tables\Columns\TextColumn::make('custom_field')
                ->getStateUsing(fn ($record) => $record->payload['custom_field'] ?? 'N/A'),
        ]);
}

Job Retry Logic: Use the monitor to debug retries. Add a "Retry" action:

->actions([
    Tables\Actions\Action::make('retry')
        ->action(function ($record) {
            $job = unserialize($record->payload);
            dispatch($job);
        }),
])

Environment-Specific Config: Override config per environment (e.g., disable pruning in staging):

// config/filament-jobs-monitor.php
'pruning' => [
    'enabled' => env('APP_ENV') !== 'staging',
    'retention_days' => 7,
],

Testing: Mock the monitor in tests by overriding the resource:

$this->filament->registerResource(
    \Croustibat\FilamentJobsMonitor\Resources\QueueMonitorResource::class,
    \Tests\MockQueueMonitorResource::class
);

Clear Logs Safely: Use the built-in "Clear all logs" action (v4.4.0+) with confirmation:

// Automatically included in the table header actions
->headerActions([
    Tables\Actions\Action::make('clear-logs')
        ->requiresConfirmation()
        ->action(function () {
            \Croustibat\FilamentJobsMonitor\Models\QueueMonitor::truncate();
        }),
])

Localization: Translate labels using Filament’s localization system:

'resources' => [
    'label' => trans('filament-jobs-monitor::resources.job'),
    'plural_label' => trans('filament-jobs-monitor::resources.jobs'),
],

Add translations to resources/lang/{locale}/filament-jobs-monitor.php.

API Access: Expose job data via API by creating a custom API resource:

Route::get('/api/jobs', function () {
    return QueueMonitorResource::getTableRecords();
});

Webhook Triggers: Use the monitor to trigger webhooks when jobs complete/fail. Extend the model:

protected static function booted() {
    static::updated(fn ($record) => JobWebhook::dispatch($record));
}

Dark Mode: Ensure the monitor’s UI respects Filament’s dark mode by using Filament’s built-in classes (e.g., bg-gray-800 for dark backgrounds).
Queue Worker Health: Monitor worker health by adding a "Last Heartbeat" column:
```
->addColumns([
```

Filament Jobs Monitor Laravel Package