README

This plugin provides an interface for creating emails on the fly and store them in a queue to be processed later by an offline worker using a cakephp shell command.

It also contains a handy shell for previewing queued emails, a very handy tool for modifying email templates and watching the result.

Requirements

CakePHP 4.x

Installation

composer require lorenzo/cakephp-email-queue

The plugin uses Debug email transport, so make sure your email config contain it:

'EmailTransport' => [
        'Debug' => [
            'className' => 'Debug'
        ],
]

Enable plugin

bin/cake plugin load EmailQueue

Load required database table

In order to use this plugin, you need to create a database table. Required SQL is located at

# config/Schema/email_queue.sql

Just load it into your database. You are free to change the file to use an integer primary key instead of UUIDs.

Or run migrations command:

bin/cake migrations migrate --plugin EmailQueue

Usage

Whenever you need to send an email, use the EmailQueue model to create and queue a new one by storing the correct data:

use EmailQueue\EmailQueue;
EmailQueue::enqueue($to, $data, $options);

enqueue method receives 3 arguments:

First argument is a string or array of email addresses that will be treated as recipients.
Second arguments is an array of view variables to be passed to the email template
Third arguments is an array of options, possible options are

subject: Email's subject
send_at: date time sting representing the time this email should be sent at (in UTC)
template: the name of the element to use as template for the email message. (maximum supported length is 100 chars)
layout: the name of the layout to be used to wrap email message
format: Type of template to use (html, text or both)
headers: A key-value list of headers to send in the email
theme: The View Theme to find the email templates
config: the name of the email config to be used for sending
from_name: String with from name. Must be supplied together with from_email.
from_email: String with from email. Must be supplied together with from_name.

Previewing emails

It is possible to preview emails that are still in the queue, this is very handy during development to check if the rendered email looks at it should; no need to queue the email again, just make the changes to the template and run the preview again:

# bin/cake EmailQueue.preview

Sending emails

Emails should be sent using bundled Sender command, use -h modifier to read available options

# bin/cake EmailQueue.sender -h

You can configure this command to be run under a cron or any other tool you wish to use.

Contributing

Run the tests

./vendor/bin/phpunit tests/

Check style

./vendor/bin/phpcs ./src ./tests/ --standard=vendor/cakephp/cakephp-codesniffer/CakePHP

lorenzo / cakephp-email-queue

Maintainers

Details