Mail Plugin

A powerful email management plugin for Festi Framework that provides a flexible system for sending emails, managing templates, and logging all communications.

Features

  • Email template management through admin interface
  • SMTP support
  • HTML emails with template system
  • Email attachments
  • Comprehensive logging system
  • Extensible through hooks

Installation

Requirements

  • PHPMailer library
    composer require phpmailer/phpmailer:^6.5

Setup

  1. Add the plugin to your project.
  2. Migrate the database install/install.[mysql|pgsql].sql
  3. Configure the project in config.php:
// Define cache path
define('MAIL_CACHE_PATH', '/path/to/cache/dir/');

// OR use global config
$GLOBALS['config']['paths'] = array(
    'cache' => FS_ROOT.'cache'.DIRECTORY_SEPARATOR
);

// SMTP Configuration (optional)
$GLOBALS['config']['smtp'] = array( 
    'from'      => '[email protected]',
    'host'      => 'ssl://smtp.yourdomain.com',
    'port'      => '465',
    'auth'      => true,
    'username'  => 'your-username',
    'password'  => 'your-password'
);

Usage

Creating Email Templates

Create a template in the database:

INSERT INTO `email_templates` (`ident`, `caption`, `subject`, `body`) VALUES
('welcome_email', 'Welcome Email', 'Welcome to our service, <?php echo $user->name; ?>', '<html><body>Thank you for joining our service!<br/><br/>Your account details:<br/><?php echo $user->details; ?></body></html>');

Sending Emails

Basic usage:

// Data to be used in the email template
$emailData = array(
    'user' => $userObject
);

// Send the email
$this->plugin->mail->send(
    '[email protected]',   // Recipient email (string or array)
    'welcome_email',           // Template identifier
    $emailData                 // Data for template
);

With attachments:

$files = array(
    '/path/to/file1.pdf',
    '/path/to/file2.jpg'
);

$this->plugin->mail->send(
    array('[email protected]', '[email protected]'),  // Multiple recipients
    'invoice_email',
    $emailData,
    $files                                           // Attachments
);

Advanced Configuration

Custom email headers:

$emailData = array(
    'mail_from'      => '[email protected]',       // Custom sender email
    'mail_from_name' => 'Custom Sender Name',       // Custom sender name
    'charset'        => 'UTF-8',                    // Custom charset
    'replay_email'   => '[email protected]',     // Reply-to email
    'replay_name'    => 'Reply Name'                // Reply-to name
);

$this->plugin->mail->send('[email protected]', 'template_ident', $emailData);

Display all recipients in a single email (BCC off):

$this->plugin->mail->setDisplayRecipients(true);
$this->plugin->mail->send(array('[email protected]', '[email protected]'), 'template_ident', $data);

Email Templates with Layouts

Create a template file in plugins/Mail/templates/:

// plugins/Mail/templates/welcome.phtml
<html>
    <head>
        <title><?php echo $title; ?></title>
    </head>
    <body>
        <div class="header">Welcome to Our Service</div>

        <div class="content">
            <?php echo $mailBody; ?>
        </div>

        <div class="footer">
            Best regards,<br>
            The Team
        </div>
    </body>
</html>
Update email template to use file:

Update your email template to use this layout:

UPDATE `email_templates` 
SET `template` = 'welcome', `title` = 'Welcome Email' 
WHERE `ident` = 'welcome_email';

Admin Interface

Setting Up Email Template Management

Execute the following SQL to create the necessary permissions:

INSERT INTO `festi_sections` (`caption`, `ident`, `mask`)
VALUES ('Manage Email Templates', 'manage_email_templates', '6');

SET @id_section_manage_email_templates = (SELECT `id`
                                  FROM `festi_sections`
                                  WHERE `ident` = 'manage_email_templates');

SET @id_user_type_admin = (SELECT `id`
                           FROM `users_types`
                           WHERE `ident` = 'admin');

INSERT INTO `festi_sections_user_types_permission` (`id_section`, `id_user_type`, `value`)
VALUES (@id_section_manage_email_templates, @id_user_type_admin, '6');

Add menu item and URL rule:

SET @id_section_manage_email_templates = (SELECT `id`
                                          FROM `festi_sections`
                                          WHERE `ident` = 'manage_email_templates');
-- Add Mail plugin
INSERT INTO `festi_plugins` (`status`, `ident`)
VALUES ('active', 'Mail');

-- Add link for manage email templates page
INSERT INTO `festi_section_actions` (`id_section`, `plugin`, `method`, `mask`, `comment`) VALUES
    (@id_section_manage_email_templates, 'Mail', 'onDisplayTemplates', '6', '');

INSERT INTO `festi_url_rules` (`plugin`, `pattern`, `method`)
VALUES ('Mail', '~^/manage/email/templates/$~', 'onDisplayTemplates');

SET @id_url_rule = (SELECT `id`
                    FROM `festi_url_rules`
                    WHERE `plugin` = 'Mail'
                      AND `method` = 'onDisplayTemplates');

INSERT INTO `festi_url_rules2areas` (`id_url_rule`, `area`)
VALUES (@id_url_rule, 'backend');

-- Add menu item
INSERT INTO `festi_menus` (`caption`, `url`, `id_parent`, `order_n`, `description`, `id_section`, `area`, `ident`)
VALUES ('Email Templates', '/manage/email/templates/', NULL, 30, NULL, @id_section_manage_email_templates, NULL, NULL);

After completing setup, you can manage email templates at /manage/email/templates/.

Extension Points

Hooks

The plugin provides the following hooks:

  • HOOK_MAIL_HEADERS: Modify email headers before sending
  • HOOK_MAIL_CONTENT: Modify email content before sending

Example usage:

public function onHookMailHeaders(array &$data)
{
    // Add CC recipients
    $data['cc_recipients'] = array('[email protected]');

    // Change from address for specific templates
    if (isset($data['data']['template_type']) && $data['data']['template_type'] == 'billing') {
        $data['from_email'] = '[email protected]';
        $data['from_name'] = 'Billing Department';
    }
}

public function onHookMailContent(array &$data)
{
    // Access the PHPMailer instance
    $mail = $data['mail'];

    // Add custom headers
    $mail->addCustomHeader('X-Priority', '1');

    // Modify content for specific templates
    if ($data['ident'] == 'emergency_alert') {
        $mail->Subject = 'URGENT: ' . $mail->Subject;
    }
}