PHP Luminova: Email Sending Integration with Mailer Class

The Luminova Mailer class simplifies the process of sending emails. It provides methods to handle various aspects of email composition, such as setting recipients, sender address, message body, attachments, and more.

It also supports third-party PHP mailer libraries like PHPMailer and SwiftMailer, allowing you to switch between mailer clients without the need to rewrite your code.

Guides

By default, the Mailer class uses a simple email class NovaMailer to send emails. If you wish to switch to a more advanced mailer, you can use PHPMailer or SwiftMailer, which are already implemented in the Luminova framework.

To use another mailer library, you need to initialize the Mailer class with your preferred PHP mailer library like PHPMailer or SwiftMailer, or set your preferred mailer class in /app/Config/Preference.php.

Initializing with PHPMailer:

use \Luminova\Email\Clients\PHPMailer;

$mailer = new Mailer(PHPMailer::class);

Initializing with SwiftMailer:

use \Luminova\Email\Clients\SwiftMailer;
$mailer = new Mailer(SwiftMailer::class);

Note:To use either PHPMailer or SwiftMailer, you will need to install the package first using Composer:

For PHPMailer:

composer require phpmailer/phpmailer

For SwiftMailer:

composer require "swiftmailer/swiftmailer:^6.0"

Usage Examples

Creating mailer instance to send email.

namespace App\Controllers\Http;

use \Luminova\Base\BaseController;
use \Luminova\Email\Mailer;

class MailerController extends BaseController
{
    public function sendEmail(): int
    {
        (new Mailer())->from('[email protected]')
            ->address('[email protected]')
            //->notification('[email protected]')
            //->addresses('[email protected],[email protected]')
            //->cc('[email protected]')
            //->bcc('[email protected]')
            //->reply('[email protected]')
            //->isMail()
            //->isHtml()
            //->options()
            //->addHeader(...)
            //->addFile(...)
            //->addFile(...)
            ->subject('Email Hello!')
            ->body('<p>HTML email message body</p>')
            ->text('Alt text email body!')
            ->send();

        // ...
    }
}

Creating a Mailer Controller Class.

namespace App\Controllers\Http;

use \Luminova\Base\BaseController;
use \App\Utils\OrderTemplate;
use \Luminova\Email\Mailer;

class MailerController extends BaseController
{
    public function sendEmail(): int
    {
        (new Mailer())
            ->from('[email protected]')
            ->address('[email protected]')
            //->body(new OrderTemplate()) Optionally set the mail template in body
            ->send(new OrderTemplate());

        // ...
    }
}

Class Definition

• Class namespace: \Luminova\Email\Mailer
• This class implements: \Luminova\Interface\LazyInterface

Methods

Learn how to create reusable email template using Base Email Template Class.

getInstance

Initialize and retrieve the singleton instance of the Mailer class.

This method ensures that only one instance of the Mailer class is created and provides global access to that instance. If no instance exists, it will instantiate the Mailer with the provided interface.

public static getInstance(MailerInterface|string|null $interface = null): static

Parameters:

Return Value:

Luminova\Email\Mailer - Returns the shared singleton instance of the Mailer class.

getClient

Retrieve the Mailer client instance.

This method returns an instance of the mail client in use.

public getClient(): \Luminova\Interface\MailerInterface

Return Value:

\Luminova\Interface\MailerInterface - Return he Mailer client instance.

Example:

$client = $mailer->getClient() // Luminova mailer client interface
    ->getMailer(); // e.g, PHPMailer instance

isHtml

Set the email format to HTML or plain text.

This method sets whether the email should be sent as HTML or plain text.By default, it sends HTML. If you want to send a plain text email, pass false to the method.

public isHtml(bool $html = true): self 

Parameters:

Return Value:

self - Return the Mailer class instance.

isMail

Set the mail transport method to either Mail or SMTP.

This method determines whether to send emails using the PHP mail() function or via SMTP. By default, it uses mail(). To send emails via SMTP, pass false to this method.

public isMail(bool $mail = true): self 

Parameters:

Return Value:

self - Return the Mailer class instance.

to

Send email to a single address.

public static to(string $address): static

Parameters:

Return Value:

static - Return new static mailer class instance.

Throws:

• \Luminova\Exceptions\MailerException - Throws if error occurred while sending email.

address

Add an email address to the recipient list.

public address(string $address, string $name = ''): self

Parameters:

Return Value:

self - Return the Mailer class instance.

addresses

Add one or more email addresses to the recipient list.

This method supports various input formats, including a comma-separated string, a numeric array of addresses, or an associative array of name-email pairs.

public addresses(string|array $address): self

Parameters:

Return Value:

self - Return the Mailer class instance.

Add multiple addresses:

// as comma-separated string
$mailer->addresses('[email protected],[email protected]');

// as an indexed array
$mailer->addresses([
    '[email protected]',
    '[email protected]'
]);

// as associated names
$mailer->addresses([
    'John' => '[email protected]',
    'Deo' => '[email protected]'
]);

addHeader

Add a custom header to the email.

The header is specified by a key (the header name), and the optional value (the header's value). If no value is provided, the header will be added without a value.

public addHeader(string $name, ?string $value = null): self

Parameters:

Return Value:

self - Return the Mailer class instance.

reply

Add a reply-to address.

public reply(string $address, string $name = ''): self

Parameters:

Return Value:

self - Return the Mailer class instance.

notification

Set the notification address for read and delivery receipts.

This method allows you to specify an email address where notifications should be sent regarding the status of the email, such as delivery or read receipts.

public notification(string $address): self

Parameters:

Return Value:

self - Return the Mailer class instance.

cc

Add an email address to the recipient list.

public cc(string $address, string $name = ''): self

Parameters:

Return Value:

self - Return the Mailer class instance.

bcc

Add an email address to the recipient list.

public bcc(string $address, string $name = ''): self

Parameters:

Return Value:

self - Return the Mailer class instance.

from

Set the email sender's address.

public from(string $address, string $name = '', bool $auto = true): self

Parameters:

Return Value:

self - Return the Mailer class instance.

body

Sets the body of the email message.

public body(\Luminova\Base\BaseMailer|string $message): self

Parameters:

Return Value:

self - Return the Mailer class instance.

text

Sets the text alternative body of the email message.

public text(string $message): self

Parameters:

Return Value:

self - Return the Mailer class instance.

subject

Sets the subject of the email message.

public subject(string $subject): self

Parameters:

Return Value:

self - Return the Mailer class instance.

options

Set SMTP stream options.

This method allows you to define custom stream context options for the SMTP connection. It can be used to configure SSL/TLS behavior, such as disabling peer verification or allowing self-signed certificates.

public options(array $smtpOptions): self 

Parameters:

Return Value:

self - Return the Mailer class instance.

Example:

$mailer->options([
    'ssl' => [
        'verify_peer' => false,
        'verify_peer_name' => false,
        'allow_self_signed' => true,
    ]
]);

addFile

Add an attachment from a path on the filesystem.

public addFile(
    string $path, 
    string $name = '', 
    string $encoding = 'base64', 
    string $type = '', 
    string $disposition = 'attachment'
): self

Parameters:

Return Value:

self - Return the Mailer class instance.

Throws:

• \Luminova\Exceptions\MailerException - Throws if error occurred while sending email.

send

Send the email.

public send(\Luminova\Base\BaseMailer|string|null $message = null): bool

Parameters:

Return Value:

bool - True if the email was sent successfully, false otherwise.

Throws:

• \Luminova\Exceptions\MailerException - Throws if error occurred while sending email.