Luminova Framework

PHP Luminova: Email Sending Integration with Mailer Class

Last updated: 2024-08-28 23:58:01

The Mailer class provides methods to facilitate sending emails. This documentation outlines its methods and their usage.

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.


  • Class namespace: \Luminova\Email\Mailer

Methods

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:

<?php
use \Luminova\Email\Clients\PHPMailer;
$mailer = new Mailer(PHPMailer::class);

Initializing with SwiftMailer:

<?php
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"

to

Send email to a single address.

public static to(string $address): static

Parameters:

ParameterTypeDescription
$addressstringEmail address to send email to.

Return Value:

static - Return new static mailer class instance.

Throws:


getClient

Get the Mailer client instance.

public getClient(): \Luminova\Interface\MailerInterface

Return Value:

\Luminova\Interface\MailerInterface - The Mailer client instance.


address

Add an email address to the recipient list.

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

Parameters:

ParameterTypeDescription
$addressstringThe email address.
$namestringThe recipient's name (optional).

Return Value:

self - Return the Mailer class instance.


replyTo

Add a reply-to address.

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

Parameters:

ParameterTypeDescription
$addressstringThe email address.
$namestringThe recipient's name (optional).

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:

ParameterTypeDescription
$addressstringThe email address.
$namestringThe recipient's name (optional).

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:

ParameterTypeDescription
$addressstringThe email address.
$namestringThe recipient's name (optional).

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:

ParameterTypeDescription
$addressstringThe email address.
$namestringThe sender's name (optional).
$autoboolWhether to automatically add the sender's name (optional).

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:

ParameterTypeDescription
$message\Luminova\Base\BaseMailer|stringThe body content of the email.

Return Value:

self - Return the Mailer class instance.


text

Sets the text alternative body of the email message.

public text(string $message): self

Parameters:

ParameterTypeDescription
$messagestringThe alternative body content of the email.

Return Value:

self - Return the Mailer class instance.


subject

Sets the subject of the email message.

public subject(string $subject): self

Parameters:

ParameterTypeDescription
$subjectstringThe subject of the email.

Return Value:

self - Return the Mailer class instance.


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:

ParameterTypeDescription
$pathstringPath to the attachment
$namestringOverrides the attachment name
$encodingstringFile encoding (see $Encoding)
$typestringMIME type, e.g. image/jpeg; determined automatically from $path if not specified
$dispositionstringDisposition to use

Return Value:

self - Return the Mailer class instance.

Throws:


send

Send the email.

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

Parameters:

ParameterTypeDescription
$message\Luminova\Base\BaseMailer|string|nullOptionally pass message body in send method.

Return Value:

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

Throws:


Examples

Creating mailer instance to send email.

<?php
namespace App\Controllers;

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

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

        // ...
    }
}

Creating a mailer template controller class.

<?php
namespace App\Controllers;

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

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

        // ...
    }
}