Swiftmailer Database S3 Spool Bundle Laravel Package

Getting Started

Minimal Setup

1. Install via Composer:

   composer require cgonser/swiftmailer-database-s3-spool-bundle:dev-master
   

   (Note: Use dev-master as the package is outdated; pin to a specific commit if needed.)

2. Enable the Bundle: Add to config/bundles.php (Symfony 4+):

   return [
       // ...
       Cgonser\SwiftMailerDatabaseS3SpoolBundle\CgonserSwiftMailerDatabaseS3SpoolBundle::class => ['all' => true],
   ];
   

3. Configure AWS SDK: Install the AWS SDK:

   composer require aws/aws-sdk-php
   

   Configure credentials in config/packages/aws.yaml:

   aws:
       credentials:
           key: '%env(AWS_ACCESS_KEY_ID)%'
           secret: '%env(AWS_SECRET_ACCESS_KEY)%'
       region: '%env(AWS_DEFAULT_REGION)%'
   

4. Configure the Bundle: Add to config/packages/cgonser_swift_mailer_database_s3_spool.yaml:

   cgonser_swift_mailer_database_s3_spool:
       s3:
           bucket: 'your-bucket-name'
           region: '%env(AWS_DEFAULT_REGION)%'
           folder: 'emails'  # Optional
   

5. First Use Case: Replace your SwiftMailer transport with the bundle’s spool:

   # config/packages/mailer.yaml
   framework:
       mailer:
           transports:
               async_s3:
                   spool: { type: 'database_s3' }
           default_transport: 'async_s3'
   

Implementation Patterns

Core Workflow

1. Spooling Emails:

   • Emails are stored in the database (via Doctrine) with metadata (recipients, subject, etc.).
   • Attachments are uploaded to S3 as files (e.g., emails/1234567890_attachment.pdf).
   • Useful for async sending (e.g., cron jobs) or retry logic.

2. Sending Emails:

   • Implement a command to fetch emails from the database, download attachments from S3, and send via SwiftMailer:

     use Cgonser\SwiftMailerDatabaseS3SpoolBundle\Command\SendEmailsCommand;
     
     // In a custom command or service:
     $sender = $this->get('cgonser_swift_mailer_database_s3_spool.sender');
     $sender->sendQueuedEmails(10); // Send up to 10 emails
     

   • Schedule this command in a cron job (e.g., every 5 minutes).

3. Integration with SwiftMailer:

   • The bundle replaces the default spool with a custom DatabaseS3Spool transport.
   • Ensure your Mailer service is configured to use this transport:

     $mailer->getTransport()->start();
     

4. Attachment Handling:

   • Attachments are stored as files on S3. Reference them in the database via filenames.
   • Example entity structure (extend the bundle’s Email entity if needed):

     /**
      * @ORM\Entity
      */
     class Email {
         // ...
         private $attachmentPaths = []; // Array of S3 paths (e.g., ['emails/123_attachment.pdf'])
     }
     

5. Retry Logic:

   • Use the database to track failed sends (e.g., add a sent_at and failed_at column).
   • Filter emails by sent_at IS NULL and retry them.

Advanced Patterns

1. Dynamic S3 Buckets/Folders:

   • Override the bundle’s S3Client service to dynamically resolve buckets/folders:

     # config/services.yaml
     services:
         Cgonser\SwiftMailerDatabaseS3SpoolBundle\S3\S3Client:
             arguments:
                 $bucket: '%env(S3_BUCKET_DYNAMIC)%'
     

2. Custom Email Entity:

   • Extend the bundle’s Email entity to add custom fields (e.g., template_id, priority):

     use Cgonser\SwiftMailerDatabaseS3SpoolBundle\Entity\Email as BaseEmail;
     
     class CustomEmail extends BaseEmail {
         private $templateId;
         // ...
     }
     

   • Update the bundle’s EmailRepository to work with your entity.

3. Batching:

   • Process emails in batches to avoid memory issues:

     $sender->sendQueuedEmails(50); // Send 50 emails at a time
     

4. Logging:

   • Log sent/failed emails for debugging:

     $logger = $this->get('logger');
     $logger->info('Sent email', ['email_id' => $email->getId()]);
     

5. Testing:

   • Mock the S3 client and database in tests:

     $this->mock(S3Client::class)
          ->shouldReceive('putObject')
          ->once();
     

Gotchas and Tips

Pitfalls

1. Outdated Package:

   • The package is abandoned (last release in 2017). Expect compatibility issues with modern Laravel/Symfony.
   • Workaround: Fork the repo and update dependencies (e.g., AWS SDK, Doctrine, SwiftMailer).

2. S3 Permissions:

   • Ensure the IAM user has s3:PutObject and s3:GetObject permissions for the bucket/folder.
   • Debugging: Check S3 logs or AWS CloudTrail for access denied errors.

3. Database Schema:

   • The bundle assumes a specific schema (e.g., emails table with attachment_paths). Migrations may fail if the schema drifts.
   • Fix: Dump the bundle’s schema and compare with your database:

     php bin/console doctrine:schema:dump-sql --em=default
     

4. Attachment Corruption:

   • If attachments fail to send, verify:
     • The S3 file was uploaded correctly (check bucket manually).
     • The file path in the database matches the S3 path exactly (case-sensitive).

5. Memory Limits:

   • Large emails (e.g., with big attachments) may hit PHP’s memory limit.
   • Fix: Increase memory_limit in php.ini or stream attachments instead of loading them entirely into memory.

6. SwiftMailer Version:

   • The bundle may not work with SwiftMailer 6+. Workaround: Downgrade to SwiftMailer 5 or patch the bundle.

Debugging Tips

1. Enable Debugging:

   • Set Swift_Events_SendEvent to log all sent emails:

     Swift_Events_SendEvent::addListener(function ($event) {
         \Log::debug('Email sent', ['subject' => $event->getMessage()->getSubject()]);
     });
     

2. Check S3 Files:

   • Manually verify files exist in S3:

     aws s3 ls s3://your-bucket/emails/ --recursive
     

3. Database Queries:

   • Log SQL queries to debug spool issues:

     # config/packages/doctrine.yaml
     doctrine:
         dbal:
             logging: true
             profiling: true
     

4. Symfony Debug Toolbar:

   • Use the Profiler to inspect the DatabaseS3Spool transport and email entities.

Extension Points

1. Custom Spool Logic:

   • Override the DatabaseS3Spool class to add pre-send hooks (e.g., validate recipients):

     namespace App\SwiftMailer;
     
     use Cgonser\SwiftMailerDatabaseS3SpoolBundle\Spool\DatabaseS3Spool as BaseSpool;
     
     class CustomDatabaseS3Spool extends BaseSpool {
         public function send(Swift_Message $message) {
             // Custom logic (e.g., validate message)
             parent::send($message);
         }
     }
     

   • Register the service in config/services.yaml:

     services:
         App\SwiftMailer\CustomDatabaseS3Spool: ~
         Cgonser\SwiftMailerDatabaseS3SpoolBundle\Spool\DatabaseS3Spool:
             alias: 'App\SwiftMailer\CustomDatabaseS3Spool'
     

2. Event Listeners:

   • Listen for mailer.email_sent or mailer.email_failed events to extend functionality:

     use Symfony\Component\Mailer\EventListener\SentEvent;
     
     $mailer->addEventListener(SentEvent::class, function (SentEvent $event) {
         // Log or process sent email
     });
     

3. Custom Email Entity:

   • Replace the bundle’s Email entity entirely by:
     1. Creating a new entity (e.g., `App\Entity