ISSUE-345: async emails

Author: tatevikg1

config/config.yml

@@ -1,6 +1,7 @@
 imports:
     - { resource: services.yml }
     - { resource: doctrine.yml }
+    - { resource: packages/*.yml }
 
 # Put parameters here that don't need to change on each machine where the app is deployed
 # https://symfony.com/doc/current/best_practices/configuration.html#application-related-configuration

config/packages/messenger.yaml

@@ -0,0 +1,26 @@
+# This file is the Symfony Messenger configuration for asynchronous processing
+framework:
+    messenger:
+        # Uncomment this (and the failed transport below) to send failed messages to this transport for later handling.
+        # failure_transport: failed
+
+        transports:
+            # https://symfony.com/doc/current/messenger.html#transport-configuration
+            async_email:
+                dsn: '%env(MESSENGER_TRANSPORT_DSN)%'
+                options:
+                    auto_setup: true
+                    use_notify: true
+                    check_delayed_interval: 60000
+                retry_strategy:
+                    max_retries: 3
+                    # milliseconds delay
+                    delay: 1000
+                    multiplier: 2
+                    max_delay: 0
+
+            # failed: 'doctrine://default?queue_name=failed'
+
+        routing:
+            # Route your messages to the transports
+            'PhpList\Core\Domain\Messaging\Message\AsyncEmailMessage': async_email

config/services.yml

@@ -37,6 +37,11 @@ services:
         public: true
         tags: [controller.service_arguments]
 
+    # Register message handlers for Symfony Messenger
+    PhpList\Core\Domain\Messaging\MessageHandler\:
+        resource: '../src/Domain/Messaging/MessageHandler'
+        tags: ['messenger.message_handler']
+
     doctrine.orm.metadata.annotation_reader:
         alias: doctrine.annotation_reader
 

docs/AsyncEmailSending.md

@@ -0,0 +1,102 @@
+# Asynchronous Email Sending in phpList
+
+This document explains how to use the asynchronous email sending functionality in phpList.
+
+## Overview
+
+phpList now supports sending emails asynchronously using Symfony Messenger. This means that when you send an email, it is queued for delivery rather than being sent immediately. This has several benefits:
+
+1. **Improved Performance**: Your application doesn't have to wait for the email to be sent before continuing execution
+2. **Better Reliability**: If the email server is temporarily unavailable, the message remains in the queue and will be retried automatically
+3. **Scalability**: You can process the email queue separately from your main application, allowing for better resource management
+
+## Configuration
+
+The asynchronous email functionality is configured in `config/packages/messenger.yaml` and uses the `MESSENGER_TRANSPORT_DSN` environment variable defined in `config/parameters.yml`.
+
+By default, the system uses Doctrine (database) as the transport for queued messages:
+
+```yaml
+env(MESSENGER_TRANSPORT_DSN): 'doctrine://default?auto_setup=true'
+```
+
+You can change this to use other transports supported by Symfony Messenger, such as:
+
+- **AMQP (RabbitMQ)**: `amqp://guest:guest@localhost:5672/%2f/messages`
+- **Redis**: `redis://localhost:6379/messages`
+- **In-Memory (for testing)**: `in-memory://`
+
+## Using Asynchronous Email Sending
+
+### Basic Usage
+
+The `EmailService` class now sends emails asynchronously by default:
+
+```php
+// This will queue the email for sending
+$emailService->sendEmail($email);
+```
+
+### Synchronous Sending
+
+If you need to send an email immediately (synchronously), you can use the `sendEmailSync` method:
+
+```php
+// This will send the email immediately
+$emailService->sendEmailSync($email);
+```
+
+### Bulk Emails
+
+For sending to multiple recipients:
+
+```php
+// Asynchronous (queued)
+$emailService->sendBulkEmail($recipients, $subject, $text, $html);
+
+// Synchronous (immediate)
+$emailService->sendBulkEmailSync($recipients, $subject, $text, $html);
+```
+
+## Testing Email Sending
+
+You can test the email functionality using the built-in command:
+
+```bash
+# Queue an email for asynchronous sending
+bin/console app:send-test-email recipient@example.com
+
+# Send an email synchronously (immediately)
+bin/console app:send-test-email recipient@example.com --sync
+```
+
+## Processing the Email Queue
+
+To process queued emails, you need to run the Symfony Messenger worker:
+
+```bash
+bin/console messenger:consume async_email
+```
+
+For production environments, it's recommended to run this command as a background service or using a process manager like Supervisor.
+
+## Monitoring
+
+You can monitor the queue status using the following commands:
+
+```bash
+# View the number of messages in the queue
+bin/console messenger:stats
+
+# View failed messages
+bin/console messenger:failed:show
+```
+
+## Troubleshooting
+
+If emails are not being sent:
+
+1. Make sure the messenger worker is running
+2. Check for failed messages using `bin/console messenger:failed:show`
+3. Verify your mailer configuration in `config/parameters.yml`
+4. Try sending an email synchronously to test the mailer configuration

src/Domain/Messaging/Command/SendTestEmailCommand.php

@@ -15,7 +15,7 @@
 
 class SendTestEmailCommand extends Command
 {
-    protected static $defaultName = 'app:send-test-email';
+    protected static $defaultName = 'phplist:test-email';
     protected static $defaultDescription = 'Send a test email to verify email configuration';
 
     private EmailService $emailService;
@@ -30,7 +30,8 @@ protected function configure(): void
     {
         $this
             ->setDescription(self::$defaultDescription)
-            ->addArgument('recipient', InputArgument::OPTIONAL, 'Recipient email address');
+            ->addArgument('recipient', InputArgument::OPTIONAL, 'Recipient email address')
+            ->addOption('sync', null, InputArgument::OPTIONAL, 'Send email synchronously instead of queuing it', false);
     }
 
     protected function execute(InputInterface $input, OutputInterface $output): int
@@ -49,17 +50,28 @@ protected function execute(InputInterface $input, OutputInterface $output): int
         }
 
         try {
-            $output->writeln('Sending test email to ' . $recipient);
+            $syncMode = $input->getOption('sync');
+
+            if ($syncMode) {
+                $output->writeln('Sending test email synchronously to ' . $recipient);
+            } else {
+                $output->writeln('Queuing test email for ' . $recipient);
+            }
 
             $email = (new Email())
                 ->from(new Address('admin@example.com', 'Admin Team'))
                 ->to($recipient)
                 ->subject('Test Email from phpList')
                 ->text('This is a test email sent from phpList Email Service.')
                 ->html('<h1>Test</h1><p>This is a <strong>test email</strong> sent from phpList Email Service</p>');
-            
-            $this->emailService->sendEmail($email);
-            $output->writeln('Test email sent successfully!');
+
+            if ($syncMode) {
+                $this->emailService->sendEmailSync($email);
+                $output->writeln('Test email sent successfully!');
+            } else {
+                $this->emailService->sendEmail($email);
+                $output->writeln('Test email queued successfully! It will be sent asynchronously.');
+            }
 
             return Command::SUCCESS;
         } catch (Exception $e) {

src/Domain/Messaging/Message/AsyncEmailMessage.php

@@ -0,0 +1,58 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpList\Core\Domain\Messaging\Message;
+
+use Symfony\Component\Mime\Email;
+
+/**
+ * Message class for asynchronous email processing
+ */
+class AsyncEmailMessage
+{
+    private Email $email;
+    private array $cc;
+    private array $bcc;
+    private array $replyTo;
+    private array $attachments;
+
+    public function __construct(
+        Email $email,
+        array $cc = [],
+        array $bcc = [],
+        array $replyTo = [],
+        array $attachments = []
+    ) {
+        $this->email = $email;
+        $this->cc = $cc;
+        $this->bcc = $bcc;
+        $this->replyTo = $replyTo;
+        $this->attachments = $attachments;
+    }
+
+    public function getEmail(): Email
+    {
+        return $this->email;
+    }
+
+    public function getCc(): array
+    {
+        return $this->cc;
+    }
+
+    public function getBcc(): array
+    {
+        return $this->bcc;
+    }
+
+    public function getReplyTo(): array
+    {
+        return $this->replyTo;
+    }
+
+    public function getAttachments(): array
+    {
+        return $this->attachments;
+    }
+}

src/Domain/Messaging/MessageHandler/AsyncEmailMessageHandler.php

@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpList\Core\Domain\Messaging\MessageHandler;
+
+use PhpList\Core\Domain\Messaging\Message\AsyncEmailMessage;
+use PhpList\Core\Domain\Messaging\Service\EmailService;
+use Symfony\Component\Messenger\Attribute\AsMessageHandler;
+
+/**
+ * Handler for processing asynchronous email messages
+ */
+#[AsMessageHandler]
+class AsyncEmailMessageHandler
+{
+    private EmailService $emailService;
+
+    public function __construct(EmailService $emailService)
+    {
+        $this->emailService = $emailService;
+    }
+
+    /**
+     * Process an asynchronous email message by sending the email
+     */
+    public function __invoke(AsyncEmailMessage $message): void
+    {
+        $this->emailService->sendEmailSync(
+            $message->getEmail(),
+            $message->getCc(),
+            $message->getBcc(),
+            $message->getReplyTo(),
+            $message->getAttachments()
+        );
+    }
+}