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
- Add the plugin to your project.
- Migrate the database
install/install.[mysql|pgsql].sql
- 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 sendingHOOK_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;
}
}