Mailbox Persistence Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require digitalshift/mailbox-persistence-bundle
   

   Enable it in config/bundles.php:

   return [
       // ...
       Digitalshift\MailboxPersistenceBundle\DigitalshiftMailboxPersistenceBundle::class => ['all' => true],
   ];
   

2. Configuration Update config/packages/digitalshift_mailbox_persistence.yaml (or create it):

   digitalshift_mailbox_persistence:
       driver: 'doctrine' # or 'filesystem' for testing
       filesystem:
           directory: '%kernel.project_dir%/var/mailbox'
       doctrine:
           entity: App\Entity\MailboxMessage # Your custom entity
           repository: App\Repository\MailboxMessageRepository
   

3. First Use Case Persist an incoming email (e.g., in a Symfony Mailer transport listener):

   use Digitalshift\MailboxPersistenceBundle\Persistence\MailboxPersisterInterface;
   
   public function handle(Message $message, Transport $transport)
   {
       $persister = $this->container->get(MailboxPersisterInterface::class);
       $persister->persist($message);
   }
   

Implementation Patterns

Core Workflows

1. Email Persistence

   • Incoming Emails: Use MailboxPersisterInterface in a Symfony TransportListener or MessageListener.
   • Outgoing Emails: Persist after sending via SwiftMailer event listeners (e.g., SentEvent).

   $persister->persist($message, [
       'user_id' => $user->getId(), // Custom metadata
       'folder'  => 'sent',
   ]);
   

2. Attachment Handling

   • Attachments are auto-saved to filesystem or linked via doctrine (configurable).
   • Retrieve attachments via the entity’s getAttachments() method or repository queries.

3. Rendering/Editing

   • Use the MailboxRenderer service to generate HTML/Plaintext previews:

   $renderer = $this->container->get('digitalshift_mailbox_persistence.renderer');
   $html = $renderer->render($mailboxMessage);
   

4. Swift Forwarding

   • Leverage the MailboxForwarder to forward persisted emails via SwiftMailer:

   $forwarder = $this->container->get('digitalshift_mailbox_persistence.forwarder');
   $forwarder->forward($mailboxMessage, $recipientEmail);
   

Integration Tips

• Doctrine ORM: Extend the default MailboxMessage entity to add custom fields (e.g., readAt, labels).
• Symfony Messenger: Dispatch PersistMailboxMessage messages for async processing.
• APIs: Expose persisted emails via API Platform or custom controllers:

  #[Route('/mailbox/{id}', methods: ['GET'])]
  public function getMailboxMessage(MailboxMessage $message): JsonResponse
  {
      return $this->json($message->toArray());
  }
  

Gotchas and Tips

Pitfalls

1. Filesystem Permissions

   • Ensure var/mailbox is writable by the web server (e.g., chmod -R 775 var/mailbox).

2. Doctrine Entity Mapping

   • If using doctrine, ensure your custom entity maps to the expected fields (e.g., from, to, subject, body).
   • Override the default MailboxMessage entity by configuring doctrine.entity in the bundle config.

3. Attachment Storage

   • Filesystem storage may bloat var/. For production, use cloud storage (e.g., AWS S3) via a custom AttachmentStorage service.

4. SwiftMailer Events

   • The bundle assumes SwiftMailer events are subscribed. If using Symfony Mailer, adapt listeners accordingly.

Debugging

• Log Persistence: Enable debug logging for the bundle:

  # config/packages/monolog.yaml
  handlers:
      mailbox:
          type: stream
          path: "%kernel.logs_dir%/mailbox.log"
          level: debug
          channels: ["digitalshift_mailbox"]
  

• Check Persisted Data: Verify emails are saved via:

  php bin/console digitalshift:mailbox:list
  

Extension Points

1. Custom Storage Override AttachmentStorageInterface for S3/DB storage:

   services:
       App\Storage\S3AttachmentStorage:
           arguments:
               - '@aws_s3.client'
           tags: ['digitalshift_mailbox.attachment_storage']
   

2. Event Listeners Extend persistence logic via events (e.g., MailboxMessagePersistedEvent):

   #[AsEventListener(event: MailboxMessagePersistedEvent::class)]
   public function onPersisted(MailboxMessagePersistedEvent $event) {
       // Add custom logic (e.g., index in Elasticsearch)
   }
   

3. Renderer Decorators Decorate MailboxRenderer to modify output (e.g., add tracking pixels):

   services:
       digitalshift_mailbox_persistence.renderer:
           decorates: digitalshift_mailbox_persistence.renderer
           arguments: ['@digitalshift_mailbox_persistence.renderer.inner']