包简介

Extension for Nette Framework: Easy & object-oriented way of sending & logging mails

README 文档

README

Mailing

Extension for Nette Framework: Easy & object-oriented way of sending & logging mails

Mailing extension lets you send/log emails in the object oriented world.

Overview

Downloading Mailing

Mailing is available through composer package ublaboo/mailing:

composer require ublaboo/mailing

MailFactory

MailFactory gives you a way to create your mails instances. In the background it sets some parameters, decides whether to log and email or not, tries to find mail template etc.

Mail

Mail is the base class you will extend in each of your email cases (classes). In your particular mail class you will set email senders/recipients/cc/.., basepath (if you want to send inline images), attach files, etc. There are also available config parameters (if you have put them in there through config.neon).

You will send it via Mail::send() method.

Create mail class

Once you have registered mailing extension, you can create new mail class and then get MailFactory from DIC to send it:

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();
	}

}

Example mail template:

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

Mail templates

Now, there is some convention in directory structure and you should stick to it. It doesn't matter where you put your mails, but the Mail class (which your mails will inherit from) will look for template latte files in <same_directory_as_your_mails_are</templates. The name of particular template has to be in camel_case naming convention. E.g.:

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

But that is only a recommendation. You can always change your template file path by Mail::setTemplateFile(). Eg:

# ...

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

Or from the outside:

# ...

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

No templates

Of course you don't have to send mails with templates, you can just use plaintext mail body. You would do that probably in your mail class:

# ...

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

Configuration

There are some configuration options available like whether to log (or send, or both), where to log, where to find inline images from, etc

Start with registering extension in config.neon:

extensions:
	mailing: Ublaboo\Mailing\DI\MailingExtension

There are several config options:

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

Let's discuss each of these options:

do

In this option you may choose between these three directives:

log means all mails will be just stored on local disk in log directory. All mails are saved in .eml format (with possible images and attachments)
send will only send all mails, but not log
both will do both

logDirectory

That one is pretty obvious. Directory, where mail files (.eml) will be stored.

mailImagesBasePath

This is the path, where Nette\Mail\Message will look for all images that can be inline embedded in mail.

mails

This array filled with your parameters (probably mail addresses - like recipients, senders, etc) will be available in instance of each of your mail class (read more) so that you can easily set sender and recipient, bcc, cc or whatever you need for particular mail.

E.g.:

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

Log

By default, MailLogger is logging all sent Mails in log directory in format ///<mail_name.eml>. As you can see, the .eml extension is used to easily open an email file in all desktop clients.

ublaboo/mailing 适用场景与选型建议

ublaboo/mailing 是一款基于 PHP 开发的 Composer 扩展包，目前已累计 160.22k 次下载、GitHub Stars 达 8，最近一次更新时间为 2015 年 12 月 10 日，在 PHP 生态内属于活跃度较高的组件。

它主要适用于以下技术方向：「log」「mail」「extension」「nette」「mailing」等业务场景。在实际项目中，围绕这些方向常见需要落地的问题包括：接口对接、性能调优、并发安全、与既有框架（Laravel / ThinkPHP / Yii / Webman 等）的兼容适配，以及生产环境的日志埋点与稳定性保障。

我们在过去多个企业项目中使用过 ublaboo/mailing 或与其功能相近的方案，如果你在选型或落地过程中遇到问题，例如 版本兼容、二次改造、私有化封装、与内部系统对接、生产 BUG 排查，欢迎联系我们协助评估。

围绕 ublaboo/mailing 我们能提供哪些服务？

定制开发 / 二次开发

基于 ublaboo/mailing 在你已有业务上做功能扩展、字段裁剪、UI 适配、与内部账号 / 权限 / 日志系统的深度对接。

BUG 修复 & 性能优化

线上偶发问题、内存泄漏、慢查询、并发异常等排查修复；针对高流量场景做缓存、队列、索引层面的调优。

项目外包 & 长期维护

承接完整的项目从需求 → 设计 → 开发 → 上线 → 长期运维；也可按月提供技术保姆服务。

yvsm@zunyunkeji.com QQ：316430983 微信：yvsm316 西安尊云信息科技 · 专注 PHP / Go / 分布式系统研发

与 ublaboo/mailing 相关的其它包

同方向 / 同关键字的高下载量 PHP Composer 包推荐，方便对比选型：

geertw/yii2-translatable-url-rule 14

A custom URL rule class for Yii 2 which allows to create translated URL rules

slavkovrn/yii2-imagecarousel 5

The Yii2 extension uses jQuery jquery.carousel-1.1.min.js and makes image carousel from php array of structure defined.

t3brightside/gallerycontent 0

TYPO3 CMS extension to create gallery content element with preset crop ratios and pagination

egorov/yii2-uikit 0

UI Kit 3 Extension for Yii2

litalino/flarum-more-bbcode 2

Adds more BBCode

beebmx/kirby-courier 40

Courier offers a convenient and painless solution for creating emails tailored for your Kirby website.

ublaboo/mailing

包简介

关键字：