adt/mail-queue

The ultimate Nette mailing solution.

v1.8 2024-06-05 02:23 UTC

Requires

• php: ^7.1|^8.0
• adt/background-queue: ^4.22
• nette/di: ^2.3 || ~3.0
• nette/mail: ~3.0
• tracy/tracy: ^2.3

MIT

• AppsDevTeam

README

Allows in-app mail queueing and delayed sending.

1.1 Installation

composer:

composer require adt/mail-queue

config.neon:

extensions:
	adtMailQueue: ADT\MailQueue\DI\MailQueueExtension

1.1.1 Using default Queue entity

Let Doctrine know about our entity:

doctrine:
	metadata:
		ADT\MailQueue\Entity: %vendorDir%/adt/mail-queue/src/Entity

1.1.2 Using custom Queue entity

Create your own entity that extends our abstract entity:

namespace App\Model\Entity;

use Doctrine\ORM\Mapping as ORM;

/**
 * @ORM\Entity
 */
class QueueEntity extends \ADT\MailQueue\Entity\AbstractMailQueueEntry {

	/**
	 * @ORM\Column(type="text")
	 */
	protected $customProperty;

}

Let us know about your custom entity:

adtMailQueue:
	queueEntityClass: App\Model\Entity\QueueEntity

To fill custom properties of your entity when enqueueing mail, you can use second argument of enqueue:

$this->mailQueueService->enqueue($mail, [
	'customProperty' => 'customValue'
]);

or

$this->mailQueueService->enqueue($mail, function (QueueEntity $e) {
	$e->customProperty = 'customValue';
});

1.2.1 Using one and only IMailer

adtMailQueue:
	mailer: @sparkPostApiMailerService

1.2.2 Custom mailer

If you need to decide which mailer you want to use based on information in your custom Queue entity, you can implement ADT\MailQueue\Service\IMessenger interface. This interface has send($entity) method where $entity is your custom entity.

adtMailQueue:
	messenger: @queueMailerMessenger

1.3 Migration

Clear your temp/cache directory.

Generate migration and migrate:

php www/index.php migrations:diff
php www/index.php migrations:migrate

1.4 Processing enqueued messages

Use predefined console command:

php www/index.php mail-queue:process

or get ADT\MailQueue\Services\QueueService from DI container and call:

$queueService->process()

1.5 Send error handler

If you need to handle send error, you can set:

adtMailQueue:
	sendErrorHandler: @ErrorHandlerClass::handlerMethod

Handler method receives queue entry entity and exception generated on send.

1.6 Queue drained event

If you need notification when queue is drained, you can set:

adtMailQueue:
	onQueueDrained: @EventHandlerClass::handlerMethod

Event handler receives instance of OutputInterface if available, NULL otherwise.

2.1 Configuration

adtMailQueue:
    messenger: #or mailer
    queueEntityClass: #default Entity\MailQueueEntry::class,
    autowireMailer: false
    sendErrorHandler: null
    onQueueDrained: null
    lockTimeout: 600
    limit: 1000 #how many emails send
    tempDir: %tempDir%
    backgroundQueueService: @ADT\BackgroundQueue\Service
    backgroundQueueCallbackName: mailSending