Spoolmailerbundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require appventus/spoolmailerbundle
   

   Add to config/bundles.php:

   AppVentus\AvSpoolMailerBundle\AvSpoolMailerBundle::class => ['all' => true],
   

2. Configure Update config/packages/av_awesome_spool_mailer.yaml (or merge into config/packages/swiftmailer.yaml):

   av_awesome_spool_mailer:
       contact_addresses:
           admin:
               address: admin@example.com
               name: Admin Team
           noreply:
               address: noreply@example.com
               name: NoReply System
   

3. First Use Case Queue an email in a controller:

   use Symfony\Component\DependencyInjection\ContainerInterface;
   
   public function sendWelcomeEmail(ContainerInterface $container, $userEmail)
   {
       $message = (new \Swift_Message('Welcome'))
           ->setFrom($container->getParameter('contact_addresses_noreply_address'), $container->getParameter('contact_addresses_noreply_name'))
           ->setTo($userEmail)
           ->setBody('Hello!');
   
       $container->get('spool_mailer')->queueMessage($message);
   }
   

Implementation Patterns

Core Workflows

1. Spooling Emails

   • Use spool_mailer service to queue emails for later sending:

     $spoolMailer = $this->get('spool_mailer');
     $spoolMailer->queueMessage($swiftMessage);
     

   • Best Practice: Spool all non-critical emails (e.g., notifications, digests) to avoid blocking user flows.

2. Sending Instant Emails

   • Use instant_mailer for time-sensitive emails (e.g., password resets):

     $instantMailer = $this->get('instant_mailer');
     $instantMailer->send($swiftMessage);
     

3. Bulk Sending

   • Run the console command to process spooled emails:

     php bin/console swiftmailer:spool:send
     

   • Automation: Schedule this via cron (e.g., every 5 minutes) for near-real-time delivery.

Integration Tips

1. SwiftMailer Integration

   • Extend existing Swift_Message objects with metadata (e.g., tags for Mailgun):

     $message->setHeader('X-Tag', 'welcome_series');
     

2. Doctrine ORM

   • The bundle stores emails in the database. Customize the entity via Resources/config/doctrine/SpoolMailer.Message.orm.yml if needed.

3. Parameter Bag Access

   • Access configured sender addresses dynamically:

     $adminEmail = $this->getParameter('contact_addresses_admin_address');
     

4. Event Listeners

   • Hook into spool.mailer.queue or spool.mailer.send events (Symfony 2.x style) for logging/auditing.

Gotchas and Tips

Pitfalls

1. Deprecated Bundle

   • Last release in 2018. Verify compatibility with your Symfony/SwiftMailer versions (tested up to SwiftMailer 4.x).
   • Mitigation: Fork the repo if critical features are missing.

2. Console Command Quirks

   • swiftmailer:spool:send may fail silently if the spool table is empty. Add logging:

     # config/packages/monolog.yaml
     handlers:
         spool_mailer:
             type: stream
             path: "%kernel.logs_dir%/spool_mailer.log"
             level: debug
     

3. Parameter Bag Naming

   • Keys are case-sensitive and use underscores (contact_addresses_admin_address). Typos will cause ParameterNotFoundException.

4. Transaction Safety

   • Spooling emails inside a Doctrine transaction may cause deadlocks. Commit before spooling:

     $entityManager->flush(); // Commit first
     $spoolMailer->queueMessage($message);
     

Debugging Tips

1. Check Spool Table

   • Inspect av_spool_mailer_message for stuck emails:

     SELECT * FROM av_spool_mailer_message WHERE sent_at IS NULL;
     

2. SwiftMailer Debugging

   • Enable transport logging in config/packages/swiftmailer.yaml:

     transport: "%env(MAILER_DSN)%"
     spool: { type: memory } # Temporarily switch to memory spool for debugging
     

3. Event Dispatching

   • Override the spool mailer service to add debug logs:

     # config/services.yaml
     services:
         App\Service\DebugSpoolMailer:
             decorates: spool_mailer
             arguments: ['@spool_mailer']
     

Extension Points

1. Custom Spool Table

   • Override the entity mapping in Resources/config/doctrine/ to add fields (e.g., user_id for tracking):

     AppVentus\AvSpoolMailerBundle\Entity\Message:
         type: entity
         table: custom_spool_emails
         fields:
             userId:
                 type: integer
     

2. Pre-Send Hooks

   • Decorate the instant_mailer to validate emails before sending:

     $instantMailer->send($message); // Add validation logic here
     

3. Alternative Transport

   • Replace the default SwiftMailer transport with a custom one (e.g., for API-based senders like Mailgun):

     swiftmailer:
         transport: gmail
         spool: { type: db, table: av_spool_mailer_message }