Postman Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require alexeyshockov/postman-bundle
   

   Enable the bundle in AppKernel.php:

   new Alexeyshockov\PostmanBundle\PostmanBundle(),
   

2. Configure MTA (Exim4 Example):

   • Define a router (/etc/exim4/conf.d/router/postman) and transport (/etc/exim4/conf.d/transport/postman) as shown in the README.
   • Restart Exim: service exim4 restart.

3. First Use Case:

   • Send an email to your Symfony app’s domain (e.g., user@example.com).
   • The email is piped to Symfony’s postman:mail:handle command, triggering event listeners or processing logic.

Implementation Patterns

Core Workflow

1. Email Ingestion:

   • Configure your MTA to pipe incoming emails to Symfony’s console command:

     /usr/bin/php /var/www/app/app/console postman:mail:handle
     

   • Use zetacomponents/mail for parsing raw email data.

2. Event-Driven Processing:

   • Extend PostmanBundle by subscribing to events (e.g., postman.mail.received).
   • Example listener:

     use Symfony\Component\EventDispatcher\EventSubscriberInterface;
     use Alexeyshockov\PostmanBundle\Event\MailEvent;
     
     class MyMailSubscriber implements EventSubscriberInterface {
         public static function getSubscribedEvents() {
             return ['postman.mail.received' => 'onMailReceived'];
         }
     
         public function onMailReceived(MailEvent $event) {
             $mail = $event->getMail();
             // Process email (e.g., parse attachments, extract text).
         }
     }
     

3. Reply Parsing:

   • Use willdurand/email-reply-parser to handle email threads/replies:

     $parser = new \EmailReplyParser\Parser();
     $isReply = $parser->isReply($mail->getRawMessage());
     

4. Storage/Logging:

   • Log processed emails via MonologBundle:

     # app/config/config.yml
     monolog:
         handlers:
             mail_handler:
                 type: stream
                 path: "%kernel.logs_dir%/postman.log"
                 level: debug
     

5. Command Customization:

   • Override the default command in src/Alexeyshockov/PostmanBundle/Command/MailHandleCommand.php or extend it.

Gotchas and Tips

Pitfalls

1. MTA Configuration:

   • Freeze on Failure: If the command in Exim’s transport fails to execute, emails are frozen. Test with:

     chmod +x /usr/bin/php /var/www/app/app/console
     

   • Permissions: Ensure www-data (or your MTA user) has read/write access to Symfony’s var/ directory.

2. Email Parsing:

   • Encoding Issues: Raw emails may have non-UTF-8 encoding. Use mb_convert_encoding() or iconv():

     $rawMessage = mb_convert_encoding($rawMessage, 'UTF-8', 'ISO-8859-1');
     

   • Large Attachments: zetacomponents/mail may struggle with large attachments. Stream files directly to storage:

     $attachment = $mail->getAttachments()[0];
     file_put_contents($path, $attachment->getContent());
     

3. Event Dispatcher:

   • Priority Conflicts: If multiple listeners handle the same event, ensure priorities are set:

     public static function getSubscribedEvents() {
         return ['postman.mail.received' => ['onMailReceived', 10]]; // Lower = higher priority
     }
     

4. Debugging:

   • Exim Debugging: Enable Exim debug mode:

     exim -d -bS < test@example.com
     

   • Symfony Logs: Check var/logs/postman.log for processing errors.

Tips

1. Testing:

   • Use swiftmailer to simulate incoming emails in tests:

     $mailer = $this->get('mailer');
     $mailer->send($message);
     

   • Mock the MailHandleCommand in PHPUnit:

     $command = $this->getMockBuilder('Alexeyshockov\PostmanBundle\Command\MailHandleCommand')
         ->disableOriginalConstructor()
         ->getMock();
     

2. Performance:

   • Batch Processing: For high-volume inboxes, process emails in batches:

     // In your listener:
     if ($batchSize >= 100) {
         $this->processBatch();
     }
     

3. Security:

   • Sanitize Input: Validate email headers/attachments to prevent injection:

     if (strpos($header, 'Content-Disposition: attachment') !== false) {
         $filename = basename($header);
         if (!preg_match('/^[a-z0-9_\-\.]+$/i', $filename)) {
             throw new \RuntimeException('Invalid filename');
         }
     }
     

4. Extending:

   • Custom Mail Classes: Extend Zeta\Mail\Message for domain-specific logic:

     class AppMail extends \Zeta\Mail\Message {
         public function isNewsletter() {
             return strpos($this->getHeader('Subject'), 'Newsletter') !== false;
         }
     }
     

   • Override Bundle: Create a custom bundle extending PostmanBundle to replace core behavior.

5. Dependencies:

   • Colada: Use alexeyshockov/colada for queue-based processing if needed:

     $queue = new \Colada\Queue();
     $queue->push('process_email', [$mail->getId()]);