PHP Luminova: Mailer System

The Luminova Mailer class makes sending emails straightforward. It gives you simple methods to set the recipient, sender, message body, and attachments, so you don't have to deal with low-level email handling.

It also works with popular PHP mailers like PHPMailer and SwiftMailer. You can switch to any of them without rewriting your email code.

Mail Clients

Luminova uses its built-in NovaMailer by default. If you need more advanced features, you can swap it for PHPMailer or SwiftMailer. Both are already supported inside the framework.

To use a different mailer client, just pass an instance of that mailer when creating the Mailer class. The rest of your email logic stays the same.

Preferred Mail Client

You can choose which mailer Luminova should use by setting it in /app/Config/Mailer.php.

// /app/Config/Mailer.php

namespace App\Config;

final class Mailer extends Configuration
{
    /**
     * Return the mail client you want to use.
     * You can return a class name or a ready-made instance.
     * Return null to use the default NovaMailer.
     */
    public function getMailer(): MailerInterface|string|null
    {
        return PHPMailer::class;

        // Or return an instance if you need custom settings:
        // return new PHPMailer(...);
    }
}

Once you set the mail client here, Luminova will automatically use it whenever an email is sent.No extra setup is needed anywhere else.

Default Mail Client

NovaMailer

NovaMailer is Luminova's built-in mail client. It doesn't require any third-party packages.

use Luminova\Utility\Email\Clients\NovaMailer;

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

PHPMailer

To use PHPMailer, install it first:

composer require phpmailer/phpmailer

Then pass it to the Mailer constructor:

use Luminova\Utility\Email\Clients\PHPMailer;

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

SwiftMailer

Install SwiftMailer:

composer require "swiftmailer/swiftmailer:^6.0"

Then initialize it:

use Luminova\Utility\Email\Clients\SwiftMailer;

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

Note:

Passing a mail client directly to the Mailer constructor overrides whatever is set in your mailer configuration.This allows you choose a different mailer for specific cases without changing the global setting.

Examples

Mail APIs

Below is a simple example of sending an email using the Mailer class.You set who the message goes to, what it contains, and then call send().

use Luminova\Utility\Email\Mailer;

Mailer::to('[email protected]')
    ->from('[email protected]')
    ->subject('Email Hello!')
    ->body('<p>HTML email message body</p>')
    ->text('Alt text email body!')
    // Extra options you may use:
    // ->address('[email protected]')
    // ->addresses('[email protected],[email protected]')
    // ->cc('[email protected]')
    // ->bcc('[email protected]')
    // ->reply('[email protected]')
    // ->notification('[email protected]')
    // ->isMail()
    // ->isHtml()
    // ->options([...])
    // ->header('X-Custom', 'Value')
    // ->attachment('/path/to/file1.pdf')
    // ->attachment('/path/to/file2.png')
    ->send();

Sending Emails

You can send an email by creating a Mailer instance and passing in your email template.The controller below shows a simple “send welcome email” flow with validation.

// /app/Controllers/Http/MailerController.php

namespace App\Controllers\Http;

use Luminova\Base\Controller;
use Luminova\Attributes\Route;
use Luminova\Attributes\Prefix;
use Luminova\Utility\Email\Mailer;
use App\Models\Emails\EmailTemplate;

#[Prefix('/mail/(:base)')]
class MailerController extends Controller
{
    #[Route('/mail/welcome/(:string)')]
    public function sendEmail(string $email): int
    {
        // Basic validation
        $this->input->setBody(['email' => $email])
            ->addField('email', 'required|email', [
                'required' => 'Email is required',
                'email'    => 'Email is invalid'
            ]);

        if ($this->input->validate()) {
            Mailer::to($email)
                ->from('[email protected]')
                // You can also pass the template into ->body()
                // ->body(new EmailTemplate())
                ->send(new EmailTemplate());
        }

        // ...
    }
}

Sending View Contents

You don't always need a template class.You can render a view without sending the output to client and send the generated HTML directly.

// app/Controllers/Http/OrderController.php

namespace App\Controllers\Http;

use Luminova\Base\Controller;
use Luminova\Attributes\Route;
use Luminova\Attributes\Prefix;
use Luminova\Utility\Email\Mailer;

#[Prefix('/order/(:base)')]
class OrderController extends Controller
{
    #[Route('/order/complete/(:integer)')]
    public function complete(int $orderNumber): int
    {
        $contents = $this->tpl
            ->view('order_email_template')
            ->contents([
                'orderNumber' => $orderNumber,
            ]);

        if (Mailer::to('[email protected]')->send($contents)) {
            return $this->view('thank.you');
        }
    }
}

Using Promise

If you want to prepare the email content asynchronously with a promise,you can use promise()->then()->catch().

// app/Controllers/Http/OrderController.php

namespace App\Controllers\Http;

use Luminova\Base\Controller;
use Luminova\Attributes\Route;
use Luminova\Attributes\Prefix;
use Luminova\Utility\Email\Mailer;
use function Luminova\Funcs\{view, logger};

#[Prefix('/order/(:base)')]
class OrderController extends Controller
{
    #[Route('/order/complete/(:integer)')]
    public function complete(int $orderNumber): int
    {
        return $this->tpl->view('order_email_template')
            ->promise([
                'orderNumber' => $orderNumber,
            ])
            ->then(function (string $content, array $options) {
                if (Mailer::to('[email protected]')->send($content)) {
                    return view('thank.you');
                }
            })
            ->catch(function (Throwable $e) {
                logger('debug', $e->getMessage());
                return view('order.failed');
            });
    }
}

Class Definition

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

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\Utility\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]'
]);

header

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 header(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\Mailer|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,
    ]
]);

attachment

Add an attachment from a path on the filesystem.

public attachment(
    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\Mailer|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.