README

LmcMail

An email service module that provides the ability to use the View renderer of a Laminas MVC application and the installed View Helper plugins to render HTML emails.

Requirements

PHP 8.1 or higher
Laminas MVC

Installation

Install the module:

$ composer require lm-commons/lmc-mail

Composer will inject the module into the modules configuration, or you can add it manually to the modules.config.php or application.config.php.

Customize the module by copying and renaming the sample configuration file lm-commons/lmc-mail/config/lmcmail.local.php.dist to the application's config/autoload.

Configuration

LmcMail supports with the Laminas SMTP Mail Transport or the Laminas File Mail Transport and this is configured by the transport config key in the lmcmail.local.php file:

<?php
return [
    'lmc_mail' => [
        'from' => [
            'email' => 'user@example.com',
            'name' => 'User',
        ],

        // For SMTP
        'transport' => [
            'type' => 'smtp',
            'options' => [
                'host' => 'example.com',
                'connection_class' => 'plain',
                'connection_config' => [
                    'ssl' => 'tls',
                    'username' => 'user@example.com',
                    'password' => 'somepassword',
                ],
                'port' => 587,
            ],
        ]    
         // OR
            
        'transport' => [
            'type' => 'file',
            'options' => [
                'path' => '/path/to/email/folder',
            ],
        ],
    ],
];

In a development environment, it is typical to use a File Mail Transport. In a production environment, an SMTP Mail Transport will more likely be used.

The 'transport' configuration must comply with the Laminas\Mail\Transport\Factory\Factory::create method.

The 'from' configuration defines a default from address. The from address can also be specified at message creation.

Usage

The Mail service can be retrieved from the service manager:

$messageService = $serviceManager->get(LmcMail\Service\MessageService::class);

Basic example to send an HTML email:

$viewModel = new \Laminas\View\Model\ViewModel();
$viewModel->setTemplate('mail/html');
$message = $messageService->createHtmlMessage(
    ['email' => 'john@example.com', 'name' => 'John'], //from 
    ['email' => 'jane@example.com', 'name' => 'Jane'] //to
    "This is the subject line", //subject
    $viewModel); // View model

$messageService->send($message);

The 'mail/html' template must exist in the application's view template map. The HTML mail renderer will use a layout template aliased as 'mail/layout' in the view template map. This is defined in the module.config.php file.

Available methods

createHtmlMessage

 /**
  * Create an HTML message
  * @param string|Address|AddressInterface|array|AddressList|Traversable $from
  * @param string|Address|AddressInterface|array|AddressList|Traversable $to
  * @param string $subject
  * @param string|ModelInterface $nameOrModel
  * @return Message
  */
createHtmlMessage(string|Address|AddressInterface|array|AddressList|Traversable $from, 
                  string|Address|AddressInterface|array|AddressList|Traversable $to, 
                  string $subject, 
                  string|ModelInterface $nameOrModel): \Laminas\Mime\Message::class

If $nameorModel is a string, it must correspond to the view template to use.

createTextMessage

/**
 * Create a text message
 * @param string|Address|AddressInterface|array|AddressList|Traversable $from
 * @param string|Address|AddressInterface|array|AddressList|Traversable $to
 * @param string $subject
 * @param string|ModelInterface $nameOrModel
 * @return Message
 */
createTextMessage(string|Address|AddressInterface|array|AddressList|Traversable $from, 
                  string|Address|AddressInterface|array|AddressList|Traversable $to, 
                  string $subject, 
                  ModelInterface $nameOrModel): \Laminas\Mail\Message::class

If $nameorModel is a string, it must correspond to the view template to use.

send

/**
 * Send the message
 * @param Message $message
 */
send(Message $message): void

where $message can be any object of type \Laminas\Mail\Message not necessarily one created by the above methods.

Advanced Customizations

LmcMail can be customized to the applications needs.

Using view templates

LmcMail uses nested view models to render the body of HTML messages.

In a similar fashion to the view model structure of the Laminas MVC Skeleton, the body is rendered using a layout view model to which the view model parameter ($nameOrModel) to the createHtmlMessage method is added a child. The rendered output of the $nameOrModel view model is captured in the variable message which is passed to the layout view model.

A default template mail/layout is supplied is view/layout/layout.phtml. This template can be the starting point for your own layout template. The layout template can be set using the setLayoutTemplate() method. Alternatively, the mail/layout entry in the View Manager template map can be overridden to point to your template. Another alternative is to use a factory delegator to the MessageServiceFactory::class to set the layout template after the Message Service is created.

View Helpers can be used when rendering view models. A common use case is to use $this->url() to render a link to your application.

Use alternate View Resolved and View Helper Manager

LmcMail uses Service Manager aliases to get the View Resolver and View Helper Manager which resolves to the Laminas MVC resolver and manager. This allows to use any view template and helpers already defined in the application.

'aliases' => [
    // These aliases are used by the MailViewRendererFactory
    // by default, they resolve to the Laminas MVC View Helper manager and Resolver
    'lmc_mail_view_helper_manager' => 'ViewHelperManager',
    'lmc_mail_view_resolver' => 'ViewResolver',
],

If you want to use a different resolver and view helper manager, then update the aliases to point to your classes:

'aliases' => [
    'lmc_mail_view_helper_manager' => 'MyHelperManager',
    'lmc_mail_view_resolver' => 'MyViewResolver',
],

If you want to use your own renderer, then you can override the Service Manager factory:

'factories' => [
    // Override the factory with your own
    'lmc_mail_view_renderer' => MyViewRendererFactory::class,
    /* ... */
],

Event Listening

MessageService::send() triggers two events:

MessageEvent::SEND is triggered right before the message is sent by the transport service.
MessageEvent::SEND_POST is triggered right after the message has been sent by the transport service.

The listener to these events will receive an event of classMessageEvent that extends the Event class with:

A $message property containing the message. The message is also stored in an event parameter named 'message'.
A getMessage() method to get the $message property.
A setMessage(Message $message) method to set the $message property and the corresponding event parameters.

The MessageService::send() method, after triggering the MessageEvent::SEND event, will retrieve the message from the event and pass it to the transport service. This allows for the listener to modify the message if needed.

A typical use case for listening to the send events would be to log that a message was sent.

lm-commons / lmc-mail

Maintainers

Details