Filament Email Log Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require ramnzys/filament-email-log
   php artisan vendor:publish --tag="filament-email-log:migrations"
   php artisan migrate
   

   Publish the config (optional):

   php artisan vendor:publish --tag="filament-email-log:config"
   

2. Enable Logging: Add the LogEmail middleware to your app/Http/Kernel.php in the $middleware array:

   \Ramnzys\FilamentEmailLog\Middleware\LogEmail::class,
   

3. First Use Case: Visit /admin/emails (or your Filament admin path) to see a live dashboard of all sent emails. No additional configuration is needed for basic usage.

Implementation Patterns

Core Workflow

1. Logging Emails: The package automatically logs emails sent via Laravel's Mail facade or Mailer class. No manual intervention is required after middleware setup.

2. Resource Integration: The package registers a Filament resource (EmailLogResource) under the /admin/emails route. Customize it via:

   Filament::registerResource(
       EmailLogResource::class,
       // Customize options here
   );
   

3. Querying Logs: Use the EmailLog model to fetch logs programmatically:

   use Ramnzys\FilamentEmailLog\Models\EmailLog;
   
   $failedEmails = EmailLog::where('status', 'failed')->latest()->get();
   

4. Extending the Resource: Override the default resource by publishing and modifying the resource class:

   php artisan vendor:publish --tag="filament-email-log:resources"
   

   Then extend app/Filament/Resources/EmailLogResource.php.

Integration Tips

• Queue Integration: If using queued emails, ensure the LogEmail middleware runs before the StartSession middleware in Kernel.php to capture queued jobs.

• Custom Fields: Add custom metadata to emails by extending the EmailLog model or using the logEmail helper:

  use Ramnzys\FilamentEmailLog\Facades\EmailLog;
  
  EmailLog::log($mailable, [
      'custom_field' => 'value',
  ]);
  

• Soft Deletes: Enable soft deletes in the EmailLog model if needed:

  use Illuminate\Database\Eloquent\SoftDeletes;
  
  class EmailLog extends Model {
      use SoftDeletes;
      // ...
  }
  

• Search Filters: Add custom search filters to the resource by overriding the getTableFilters() method in your published resource class.

Gotchas and Tips

Pitfalls

1. Middleware Placement:

   • Issue: Emails sent via queued jobs may not log if the LogEmail middleware runs too late.
   • Fix: Place LogEmail before StartSession in $middleware (not $middlewareGroups).

2. Database Schema:

   • Issue: Custom fields added to email_logs table may break migrations if not handled carefully.
   • Fix: Publish and modify the migration:

     php artisan vendor:publish --tag="filament-email-log:migrations"
     

3. Large Log Volumes:

   • Issue: Performance degradation with thousands of logs.
   • Fix: Implement pagination in the resource or archive old logs via a scheduled job:

     EmailLog::where('created_at', '<', now()->subDays(30))->delete();
     

4. Testing:

   • Issue: Logged emails may clutter tests.
   • Fix: Use EmailLog::flush() in test tear-down or mock the LogEmail middleware.

Debugging Tips

1. Log Not Appearing?:

   • Verify the LogEmail middleware is registered in Kernel.php.
   • Check if the email is sent via Mail::send() or Mailer directly (not via Bus::dispatch() without middleware).

2. Missing Fields:

   • Ensure the email_logs table has the expected columns. Re-run migrations if needed.

3. Filament Permissions:

   • If the /admin/emails route is inaccessible, check Filament’s user permissions or resource registration.

Extension Points

1. Custom Log Storage: Override the EmailLog model to store logs in a custom database or service:

   class CustomEmailLog extends EmailLog {
       protected $connection = 'pgsql';
       // ...
   }
   

2. Email Attachments: Extract and display attachments by extending the resource’s getTableColumns() or getTableRecords() methods.

3. Webhook Triggers: Use the email.logged event to trigger actions (e.g., Slack notifications):

   EmailLog::addListener(function ($emailLog) {
       // Send notification
   });
   

4. Bulk Actions: Add bulk delete or export actions to the resource by overriding getTableActions():

   public static function getTableActions(): array {
       return [
           Tables\Actions\DeleteBulkAction::make(),
           Tables\Actions\ExportAction::make(),
       ];
   }