README

邮件

Nette 框架扩展：轻松且面向对象的发送和记录邮件方式

Mailing 扩展允许你在面向对象的世界中发送/记录邮件。

概述

下载 Mailing

Mailing 通过 composer 包 ublaboo/mailing 提供

composer require ublaboo/mailing

MailFactory

MailFactory 提供了一种创建邮件实例的方法。在后台，它会设置一些参数，决定是否记录和发送邮件，尝试查找邮件模板等。

邮件

邮件是你在每个电子邮件案例（类）中扩展的基本类。在你的特定邮件类中，你可以设置电子邮件发送者/接收者/cc/等，基本路径（如果你想要发送内联图像），附加文件等。也有可用的配置参数（如果你通过 config.neon 放置了它们）。

你将通过 Mail::send() 方法发送它。

创建邮件类

一旦你注册了邮寄扩展，你可以创建新的邮件类，然后从 DIC 获取 MailFactory 来发送它

namespace App\Mailing;

use Ublaboo\Mailing\IMessageData;

class ContactMailData implements IMessageData
{

	public function __construct(
		public readonly string $recipient,
	) 
	{
	}

}

namespace App\Mailing;

use InvalidArgumentException;
use Nette\Mail\Message;
use Ublaboo\Mailing\Mail;
use Ublaboo\Mailing\IComposableMail;
use Ublaboo\Mailing\IMessageData;

class ContactMail extends Mail implements IComposableMail
{

	public function compose(Message $message, ?IMessageData $mailData): void
	{
		if (!$mailData instanceof ContactMailData) {
			throw new InvalidArgumentException();
		}
	
		$message->setFrom($this->mailAddresses['defaultSender']);
		$message->addTo($mailData->recipient);
	}

}

namespace App\Presenters;

use App\Mailing\ContactMail;
use App\Mailing\ContactMailData;
use Nette\Application\UI\Presenter;
use Nette\DI\Attributes\Inject;
use Ublaboo\Mailing\MailFactory;

class HomepagePresenter extends Presenter
{

	#[Inject]
	public MailFactory $mailFactory;

	public function actionDefault(): void
	{
		$mail = $this->mailFactory->createByType(
			ContactMail::class, 
			new ContactMailData(
				recipient: 'hello@hello.hello'
			),
		);
		
		$mail->send();
	}

}

示例邮件模板

<!DOCTYPE html>
	<html>
	<head>
		<title>Contact mail</title>
	</head>
	<body>
		Helo, {$mailData->name}
		<br>
		Your email is: {$mailData->recipient}
	</body>
</html>

邮件模板

现在，目录结构中有些约定，你应该坚持。无论你把邮件放在哪里，但你的邮件类（你的邮件将继承自）将在 <same_directory_as_your_mails_are</templates 中查找模板 latte 文件。特定模板的名称必须符合 camel_case 命名约定。例如。

app/
	Mailing/
		ContactMail.php
		templates/
			ContactMail.latte

但这只是一个建议。你可以通过 Mail::setTemplateFile() 总是更改你的模板文件路径。例如

# ...

public function compose(Message $message, ?IMessageData $mailData): void
{
	# ...
	
	$this->setTemplateFile(__DIR__ . '/templates/ContactMail.latte');
}

或从外部

# ...

$mail = $mailFactory->createByType(ContactMail::class, new ContactMailData(recipient: 'hello@hello.hello']));
$mail->setTemplateFile('super_awesome_template.latte');

没有模板

当然，你不必使用模板发送邮件，你可以直接使用纯文本邮件正文。你可能会在邮件类中这样做

# ...

public function compose(Message $message, ?IMessageData $mailData): void
{
	# ...
	
	$message->setBody('Hello');
}

配置

有一些配置选项可供使用，如是否记录（或发送，或两者都要），在哪里记录，在哪里查找内联图像等

在 config.neon 中注册扩展以开始

extensions:
	mailing: Ublaboo\Mailing\DI\MailingExtension

有几个配置选项

mailing:
	do: both # log|send|both
	logDirectory: '%appDir%/../log/mails' # this is default option
	mailImagesBasePath: %wwwDir% # this is default option
	mails: []

让我们讨论每个这些选项

在这个选项中，你可以在以下三个指令中选择

log 表示所有邮件都将仅存储在本地磁盘的日志目录中。所有邮件都以 .eml 格式保存（可能包含图像和附件）
send 将仅发送所有邮件，但不记录
both 将执行两者

logDirectory

这个很明显。邮件文件（.eml）将被存储的目录。

mailImagesBasePath

这是 Nette\Mail\Message 查找所有可以内嵌在邮件中的图像的路径。

mails

这个数组包含你的参数（可能是邮件地址 - 如接收者、发送者等），它将在你的每个邮件类实例（阅读更多）中可用，这样你就可以轻松设置发送者、接收者、bcc、cc 或你需要的特定邮件。

例如。

mailing:
	mails: [
		defaultSender: foo@bar.baz
	]

日志

默认情况下，MailLogger 将在日志目录中以格式 ///<mail_name.eml> 记录所有发送的邮件。正如你所看到的，.eml 扩展用于轻松在所有桌面客户端中打开电子邮件文件。

ublaboo / mailing

维护者

详细信息