Milk Admin

Mail Class

The Mail class is a wrapper for PHPMailer that simplifies sending emails using PHP templates.

Main Usage

The main method for sending emails is through the use of templates:

<?php
        // Send email with template
Get::mail()->loadTemplate(MILK_DIR.'/Modules/my_module/mails/email_template.php', [
    'name' => 'John Doe',
    'user' => $user_object,
    'url' => 'https://example.com/reset-password'
])->to('destinatario@example.com')->send();

// Error handling
if (Get::mail()->getLastError()) {
    echo Get::mail()->getLastError();
}?>

Template Structure

Email templates must be built following this structure:

<?php
!defined('MILK_DIR') && die(); // Avoid direct access
ob_start();
// Email content
?>
<h1>Benvenuto <?php echo $name; ?>!</h1>
<p>Questo è un esempio di template email.</p>
<p>Puoi utilizzare variabili PHP: <?php echo $custom_var; ?></p>
<?php

$this->mail->Body    = ob_get_clean();
$this->mail->AltBody = strip_tags($this->mail->Body);
$this->mail->Subject = 'Oggetto Email';
// Additional PHPMailer parameters (optional)
$this->mail->Priority = 1; // 1 = High, 3 = Normal, 5 = Low
$this->mail->CharSet = 'UTF-8';

Public Methods

loadTemplate($path, $vars = [])

Loads a PHP template for the email. Automatically searches in the milkadmin_local path before the original path.

  • $path: template file path
  • $vars: associative array of variables to pass to the template
Get::mail()->loadTemplate('modules/user/mails/welcome.php', [
    'username' => 'Mario Rossi',
    'activation_link' => 'https://example.com/activate?token=123'
]);

config($is_smtp, $username, $password, $host, $port, $smtpSecure)

Configures SMTP or mail() settings.

  • $is_smtp: boolean - use SMTP (true) or mail() (false)
  • $username: SMTP username
  • $password: SMTP password
  • $host: SMTP host
  • $port: SMTP port (default: 465)
  • $smtpSecure: encryption type (default: PHPMailer::ENCRYPTION_SMTPS)

to(string $address, string $name = '')

Sets the email recipient. Supports multiple addresses separated by comma or semicolon.

Get::mail()->to('utente@example.com');
Get::mail()->to('utente@example.com', 'Nome Utente');
Get::mail()->to('utente1@example.com, utente2@example.com');

cc(string $address, string $name = '')

Adds carbon copy (CC) recipients.

bcc(string $address, string $name = '')

Adds blind carbon copy (BCC) recipients.

from($from, $from_name = '')

Sets the email sender.

\Get::mail()->from('from@example.com', 'Name');

replyTo($reply_to, $reply_to_name = '')

Sets the reply-to address.

subject($subject)

Sets the email subject (not recommended with load_template, use in template instead).

message($message)

Sets the email body (not recommended with load_template, use in template instead).

isHTML($is_html = false)

Sets whether the email is HTML or plain text.

addAttachment($path, $name = '')

Adds an attachment to the email.

Get::mail()->addAttachment('/path/to/file.pdf', 'document.pdf');

send()

Sends the email. Returns true if sending is successful, false otherwise.

hasError()

Checks if there were any errors during sending.

getError()

Returns the last error message.

Practical Examples

Email with Attachment

// Template: modules/reports/mails/monthly_report.php
<?php
!defined('MILK_DIR') && die();
ob_start();
?>
<p>Dear <?php echo $recipient_name; ?>,</p>
<p>Please find attached the monthly report for <?php echo $month; ?>.</p>
<p>Best regards,<br>The Team</p>
<?php
$this->mail->Body = ob_get_clean();
$this->mail->AltBody = strip_tags($this->mail->Body);
$this->mail->Subject = 'Monthly Report - ' . $month;

// Send with attachment
$mail = Get::mail();
$mail->loadTemplate('modules/reports/mails/monthly_report.php', [
    'recipient_name' => 'Manager',
    'month' => 'October 2024'
])
->to('manager@example.com')
->addAttachment('/path/to/report.pdf', 'Report_October_2024.pdf')
->send();

Customizations System

The load_template function automatically searches for templates in the milkadmin_local directory first:

// Original path:
// modules/user/mails/welcome.php

// Customizations path (has priority if exists):
// milkadmin_local/Modules/user/mails/welcome.php

Best Practices

  • Always use load_template for emails with complex layouts
  • Set Subject, Body and AltBody in the template itself
  • Use output buffering (ob_start/ob_get_clean) to capture HTML
  • Always generate a text version with strip_tags for AltBody
  • Always handle errors with getLastError()

Important Notes

  • Templates have access to the PHPMailer instance via $this->mail
  • Variables passed to load_template are available in the template
  • After send() all recipients and attachments are automatically removed
  • Methods can be chained for fluent syntax