README

LmcMail

一个电子邮件服务模块，提供使用Laminas MVC应用程序的视图渲染器和已安装的视图助手插件来渲染HTML电子邮件的能力。

需求

PHP 8.1或更高版本
Laminas MVC

安装

安装模块

$ composer require lm-commons/lmc-mail

Composer将模块注入到模块配置中，或者您可以将它手动添加到modules.config.php或application.config.php中。

通过复制并将示例配置文件lm-commons/lmc-mail/config/lmcmail.local.php.dist重命名到应用程序的config/autoload中来自定义模块。

配置

LmcMail支持Laminas SMTP邮件传输或Laminas文件邮件传输，这通过lmcmail.local.php文件中的transport配置键进行配置

<?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',
            ],
        ],
    ],
];

在开发环境中，通常使用文件邮件传输。在生产环境中，可能会更频繁地使用SMTP邮件传输。

'transport'配置必须符合Laminas\Mail\Transport\Factory\Factory::create方法。

'from'配置定义了一个默认的from地址。在消息创建时也可以指定from地址。

使用

可以从服务管理器获取邮件服务

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

发送HTML电子邮件的基本示例

$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);

'mail/html'模板必须在应用程序的视图模板映射中存在。HTML邮件渲染器将使用视图模板映射中别名作为'mail/layout'的布局模板。这定义在module.config.php文件中。

可用方法

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

如果$nameorModel是一个字符串，则它必须对应要使用的视图模板。

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

如果$nameorModel是一个字符串，则它必须对应要使用的视图模板。

send

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

其中$message可以是任何类型的对象\Laminas\Mail\Message，不一定是由上述方法创建的。

高级定制

LmcMail可以根据应用程序的需求进行定制。

使用视图模板

LmcMail使用嵌套视图模型来渲染HTML消息的正文。

类似于Laminas MVC骨架的视图模型结构，正文是通过一个布局视图模型来渲染的，该布局视图模型将createHtmlMessage方法的视图模型参数（$nameOrModel）作为子节点添加。通过变量message捕获的$nameOrModel视图模型的渲染输出传递给布局视图模型。

默认模板mail/layout是view/layout/layout.phtml。此模板可以成为您自己的布局模板的起点。可以使用setLayoutTemplate()方法设置布局模板。或者，可以将视图管理器模板映射中的mail/layout条目覆盖为指向您的模板。另一个选择是使用工厂委托到MessageServiceFactory::class，在创建消息服务后设置布局模板。

在渲染视图模型时可以使用视图助手。一个常见的用例是使用$this->url()来渲染指向您的应用程序的链接。

使用替代视图解析器和视图助手管理器

LmcMail使用服务管理器别名来获取视图解析器和视图助手管理器，它们解析为Laminas MVC解析器和管理器。这允许使用应用程序中已定义的任何视图模板和助手。

'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',
],

如果您想使用不同的解析器和视图助手管理器，则更新别名以指向您的类

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

如果您想使用自己的渲染器，则可以覆盖服务管理器工厂

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

事件监听

MessageService::send() 方法触发两个事件

MessageEvent::SEND 事件在传输服务发送消息之前立即触发。
MessageEvent::SEND_POST 事件在传输服务发送消息之后立即触发。

这些事件的监听器将接收到一个扩展自 Event 类的 MessageEvent 类的事件。

包含消息的 $message 属性。消息还存储在一个名为 'message' 的事件参数中。
使用 getMessage() 方法来获取 $message 属性。
使用 setMessage(Message $message) 方法来设置 $message 属性以及相应的イベント参数。

MessageService::send() 方法在触发 MessageEvent::SEND 事件后，将从事件中检索消息并将其传递给传输服务。这允许监听器在需要时修改消息。

监听发送事件的典型用例是记录消息已发送。

lm-commons / lmc-mail

维护者

详细信息