lm-commons / lmc-mail
Wrapper for Laminas Mail that uses View Model to compose the email body
Requires
- php: ^8.1
- laminas/laminas-mail: ^2.1
- laminas/laminas-modulemanager: ^2.1
- laminas/laminas-servicemanager: ^3.0
- laminas/laminas-view: ^2.1
Requires (Dev)
- laminas/laminas-component-installer: ^3.2
- laminas/laminas-mvc: ^3.1
- laminas/laminas-test: ^4.8
- phpunit/phpunit: ^10.0
This package is auto-updated.
Last update: 2024-11-04 15:44:41 UTC
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.