README

Fork自 eLod 的 li3_mailer 插件，用于从您的 li3 应用程序发送电子邮件消息。

安装

首选的安装方法是使用 composer。您可以通过以下方式将库添加为依赖项：

composer require atelierdisko/li3_mailer

li₃ 插件必须在应用程序引导阶段注册，因为它们使用不同的（更快的）自动加载器。

Libraries::add('li3_mailer')

官方手册提供了有关如何注册插件或使用其他安装方法（例如通过 GIT）的更多信息。

文档

邮件发送器

发送电子邮件消息涉及多个组件。为了方便管理电子邮件，插件引入了邮件发送器的概念，其职责是创建和发送消息。为此，插件实现了一个基本的 Mailer 类，它可以被继承以创建具有特定选项的邮件发送器，也可以用于发送。

在继承 Mailer 时，可以使用 $_messages 属性为每条消息或特定消息设置配置，例如

{{{ class MyMailer extends \li3_mailer\action\Mailer { protected static $_messages = array( array('cc' => array('Me' => 'my@address')), 'specific' => array('cc' => array('other@address')) ); }}

// 消息将抄送给 my@address MyMailer::deliver('test');

// 消息将抄送给 my@address 和 other@address MyMailer::deliver('specific');

// 基类也可以使用 li3_mailer\action\Mailer; Mailer::deliver('message'); }}

可以为创建（如 'from'、'to' 等）、渲染（如 'data'、'layout' 等）和发送（如 'delivery'、适配器特定的传输选项等）消息配置多个选项。

发送

通过发送服务发送电子邮件消息，可以配置该服务以处理多个配置。配置可以包含创建消息的选项（如 'from'、'to' 等）

{{{ use li3_mailer\action\Mailer; use li3_mailer\net\mail\Deliver; Delivery::config(array( 'first' => array('adapter' => 'Simple', 'from' => 'first@address'), 'second' => array('adapter' => 'Simple', 'from' => 'second@address') )); }}

// 从 first@address 发送 Mailer::deliver('test', array('delivery' => 'first'));

// 从 second@address 发送 Mailer::deliver('test', array('delivery' => 'second')); }}

与其他基于 Adaptable 的配置一样，每个发送配置都由一个名称和创建传输适配器的选项数组定义。 Delivery 还支持基于环境的配置，如

{{{ 使用 li3_mailer\net\mail\Deliver; Delivery::config(array('default' => array( 'production' => array('adapter' => 'Simple'), 'development' => array('adapter' => 'Swift') ))); }}}

内置传输适配器

• Simple：使用PHP内置函数mail发送电子邮件。
• Swift：依赖SwiftMailer库发送电子邮件。
• Mailgun：使用Mailgun托管服务发送电子邮件（依赖cURL）。
• Debug：不是发送电子邮件，而是将其记录到指定的文件或目录中。

消息

一个消息对象包含所有渲染和发送所需的相关信息。可以使用Mailer构建此类消息、获取合适的适配器并将消息传递给适配器进行投递。如前面的示例所示，消息中存储的信息可以在几个地方进行自定义，优先级依次为

• 在投递配置中
• 在邮件器的$_messages[0]中
• 在邮件器的$_messages['message_name']中
• 显式选项（例如，Mailer::deliver()的$options参数）

消息有一个特殊的属性，即$baseURL属性。通过了解其用途和使用方式，可以更容易地理解此值的用途

• 例如，在创建嵌入附件（参见后续内容）时，消息可能需要生成一个Content-ID。为了生成此唯一ID，RFC建议使用timestamp@host形式。
• 当在模板中生成URL（参见后续内容）时，应该带有方案。

此外，由于从cron脚本发送电子邮件是一个常见的用例，插件不能依赖于具有此类值的环境，该值可以在其中确定。为此，消息具有此属性，如前面所见（例如，在投递、邮件器或显式中）进行配置。为了生成正确的URL，$baseURL应具有格式scheme://host/base（例如，http://example.com/my/app）。此外，当初始化消息时，它将尝试自动检测此设置（因此，在仅从Web环境中发送电子邮件时，可以不指定此选项）。

附件

一个消息可以具有附件。以下是一个简单示例，将2个PDF文件附加到消息中：{{{'$attach' = array('file1.pdf', '/path/to/file2.pdf'); Mailer::deliver('my_message', compact('attach'));}}}

附件路径可以是相对于邮件资源路径（默认为app/mails/_assets，由Media确定，参见后续内容）。除了常规文件外，还可以附加远程文件（如果启用了allow_url_fopen）和显式内容：{{{'// 附加远程文件 $attach' = array('http://example.host/file.pdf'); Mailer::deliver('my_message', compact('attach'));}}}

// attach simple content with filename
$attach = array(array(
    'data' => 'this is my content',
    'filename' => 'cool.txt'
));
Mailer::deliver('my_message', compact('attach'));

// attach image data with content type
$img_data = create_custom_image(...);
$attach = array(array(
    'data' => $img_data,
    'filename' => 'cool.png',
    'content-type' => 'image/png'
));
Mailer::deliver('my_message', compact('attach'));

}}}

模板

渲染电子邮件消息与渲染响应类似，但有几点例外。最重要的是，电子邮件消息可能有多种类型（而没有相应的请求），而不是像响应那样有一个可以协商以推断最合适的（单一）类型的请求。为了支持这一点，插件实现了一个类似于HTTP的Media类，它可以用来注册新类型或配置内置类型。

电子邮件模板的默认基本路径是/app/mails（而不是/app/views），这样可以更好地与视图模板分离。然而，这可以通过Media类进行配置。确切的模板将由消息的名称和默认的邮件发送器确定，因此命令如Mailer::deliver('test')将使用/app/mails/test.html.php来渲染HTML内容，而FooMailer::deliver('test')将首先查找/app/mails/foo/test.html.php，如果找不到后者，则回退到前者。同样，前者命令将使用/app/mails/test.text.php模板来渲染文本（纯文本）内容。布局和元素的默认基本路径分别是/app/mails/layouts和/app/mails/elements。

与从控制器渲染类似，这些默认设置在发送邮件消息时可以被覆盖：{{{ // 渲染 /app/mails/test.{:type}.php，使用默认布局 (/app/mails/layouts/default.{:type}.php) Mailer::deliver('test'); }}

// renders /app/mails/other.{:type}.php with default layout
Mailer::deliver('test', array('template' => 'other'));

// renders /app/mails/test.text.php without layout, only text (plain) type
Mailer::deliver('test', array('types' => 'text', 'layout' => false));

}}}

辅助器和处理器

插件提供了与lithium为视图提供的类似的邮件模板辅助器：Html和Form辅助器。它们提供了与视图辅助器相同的功能。

Html辅助器的图像方法可以用来嵌入图像：{{{

我的图像：image('my/image.png'); ?>

创建或替换邮件模板辅助器的方式与常规视图辅助器相同，但邮件辅助器是以helper\mail\Name（例如应放置在app/extensions/helper/mail/Name.php）的方式命名空间化的。

处理器与辅助器非常相似，并且有两个常用的处理器，在邮件模板中的行为与视图模板略有不同

• url处理器默认会生成绝对URL。
• path处理器默认会生成绝对URL，并为嵌入生成'cid:ID'样式的值。

引用消息

在模板上下文中，$this指向Renderer对象，该对象公开了消息，因此可以添加或更改主题，添加标题或附加文件：{{{ message()->subject('My subject'); ?> message()->header('Custom', 'header'); ?> message()->attach('file.pdf'); ?> }}}

请注意，当消息有多个类型时，这些方法应只放置在一个模板中，因为多次调用它们会导致意外的行为：例如，当调用subject时，最后一个值将覆盖前面的值（渲染顺序由消息的类型顺序决定），从多个模板中附加相同的文件会导致多个相同文件的附件。

致谢

感谢 eLod、nateabele、daschl、masom 以及活跃的 li3 社区。

版权

详细信息请参阅 LICENSE.txt。