Imap Symfony Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require daddl3/imap-symfony_bundle
   

   Register the bundle in config/bundles.php:

   return [
       // ...
       Daddl3\ImapSymfonyBundle\Daddl3ImapSymfonyBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config:

   php bin/console daddl3:imap:install
   

   Edit config/packages/daddl3_imap.yaml with your IMAP server details (host, port, username, password, SSL settings).

3. First Use Case Fetch unread emails in a controller:

   use Daddl3\ImapSymfonyBundle\Service\ImapService;
   
   class EmailController extends AbstractController
   {
       public function __construct(private ImapService $imapService) {}
   
       public function index()
       {
           $unreadEmails = $this->imapService->getUnreadEmails();
           return $this->render('email/index.html.twig', ['emails' => $unreadEmails]);
       }
   }
   

Implementation Patterns

Core Workflows

1. Email Fetching

   • Fetch all emails:

     $emails = $this->imapService->getEmails(['limit' => 10]);
     

   • Fetch by criteria (e.g., unread, flagged):

     $unread = $this->imapService->getEmails(['unread' => true]);
     $flagged = $this->imapService->getEmails(['flagged' => true]);
     

2. Email Processing

   • Parse email body/attachments:

     foreach ($emails as $email) {
         $body = $email->getBody();
         $attachments = $email->getAttachments();
     }
     

   • Mark as read:

     $this->imapService->markAsRead($email->getId());
     

3. Searching

   • Use IMAP search criteria:

     $results = $this->imapService->search('SINCE "01-Jan-2023"');
     

4. Event Listeners

   • Subscribe to email events (e.g., EmailFetchedEvent):

     # config/services.yaml
     services:
         App\EventListener\EmailListener:
             tags:
                 - { name: 'kernel.event_listener', event: 'daddl3.imap.email.fetched', method: 'onEmailFetched' }
     

Integration Tips

• Caching: Cache frequent queries (e.g., unread count) using Symfony’s cache system.

  $cache = $this->cache->get('unread_emails_count', function() {
      return $this->imapService->countUnreadEmails();
  });
  

• Background Processing: Offload heavy operations (e.g., attachment downloads) to a message queue (e.g., Symfony Messenger).
• Twig Integration: Pass parsed emails to Twig for rendering:

  {% for email in emails %}
      <div class="email">
          <h3>{{ email.subject }}</h3>
          <p>{{ email.body|truncate(200) }}</p>
      </div>
  {% endfor %}
  

Gotchas and Tips

Common Pitfalls

1. Connection Issues

   • Symptom: Connection could not be established.
   • Fix: Verify daddl3_imap.yaml settings (host, port, SSL, authentication). Test with a standalone IMAP client (e.g., Thunderbird) first.
   • Debugging: Enable debug mode in config:

     daddl3_imap:
         debug: true
     

2. Character Encoding

   • Symptom: Garbled text in email bodies.
   • Fix: Explicitly set encoding when fetching:

     $emails = $this->imapService->getEmails(['charset' => 'UTF-8']);
     

3. Rate Limiting

   • Symptom: IMAP server disconnects or throttles requests.
   • Fix: Add delays between batches:

     sleep(1); // Pause between API calls
     

4. Attachment Handling

   • Symptom: Attachments not saved or corrupted.
   • Fix: Use Webklex\IMAP\Mailbox::getMessages() with fetchBody: true and fetchAttachments: true. Validate file paths and permissions.

Debugging Tips

• Log IMAP Commands: Enable Symfony’s profiler and check the daddl3_imap tab for raw IMAP traffic.
• Test Locally: Use a local IMAP server (e.g., dovecot) for development to avoid cloud provider delays.
• Timeouts: Increase PHP’s default_socket_timeout in php.ini if emails hang:

  default_socket_timeout = 300
  

Extension Points

1. Custom Mailbox Classes Extend Webklex\IMAP\Mailbox to add domain-specific logic:

   namespace App\IMAP;
   
   use Webklex\IMAP\Mailbox as BaseMailbox;
   
   class CustomMailbox extends BaseMailbox
   {
       public function getCustomField()
       {
           return $this->getHeader('X-Custom-Header');
       }
   }
   

   Register in services.yaml:

   services:
       App\IMAP\CustomMailbox: '@daddl3_imap.mailbox'
   

2. Event Customization Dispatch custom events for business logic:

   use Symfony\Contracts\EventDispatcher\EventDispatcherInterface;
   
   class EmailService
   {
       public function __construct(
           private EventDispatcherInterface $dispatcher
       ) {}
   
       public function processEmail($email)
       {
           $event = new CustomEmailEvent($email);
           $this->dispatcher->dispatch($event);
       }
   }
   

3. Configuration Overrides Override bundle config per environment:

   # config/packages/dev/daddl3_imap.yaml
   daddl3_imap:
       host: 'localhost'
       port: 143
       ssl: false