包简介

Project installation support extension for the Yii2 framework

README 文档

README

ActiveMail Extension for Yii 2

This extension provides 'active mail message' concept implementation for Yii2. Active message is a model, which knows all necessary data for self composition and can send itself.

For license information check the LICENSE-file.

Requirements

This extension requires any implementation of the Yii2 mailer, such as yiisoft/yii2-swiftmailer.

Installation

The preferred way to install this extension is through composer.

Either run

php composer.phar require --prefer-dist yii2tech/activemail

or add

"yii2tech/activemail": "*"

to the require section of your composer.json.

Note: you should install particular mailer extension such as 'yiisoft/yii2-swiftmailer' separately.

Usage

This extension provides 'active mail message' concept implementation for Yii2. ActiveMessage is a model, which knows all necessary data for self composition and can send itself. It allows email message composition based on templates stored inside PHP files or database.

In order to use this extension you need to add mail template storage component to your application:

return [
    'components' => [
        'mailTemplateStorage' => [
            'class' => 'yii2tech\activemail\TemplateStoragePhp',
            'templatePath' => '@app/mail/templates',
        ],
        // ...
    ],
    // ...
];

ActiveMessage

Each particular active message should extend [[\yii2tech\activemail\ActiveMessage]] class, implementing at least all abstract methods, which guarantees particular active message has default values for each necessary part. As a regular model it can contain attributes, which are defined via public fields. Validation rules can be setup for those attributes. For example:

namespace app\mail\active;

use yii2tech\activemail\ActiveMessage;
use Yii;

class ContactUs extends ActiveMessage
{
    public $name;
    public $email;
    public $message;
    public $subject;

    public function rules()
    {
        return [
            [$this->attributes, 'required'],
            ['email', 'email'],
        ];
    }

    public function defaultFrom()
    {
        return Yii::$app->params['applicationEmail'];
    }

    public function defaultTo()
    {
        return Yii::$app->params->mail['adminEmail'];
    }

    public function defaultSubject()
    {
        return 'Contact: {subject}';
    }

    public function defaultBodyHtml()
    {
        return <<<BODY
Email: <a href="mailto:{email}">{email}</a><br>
Name: {name}<br>
<hr>
{subject}
<hr>
{message}
BODY;
    }
}

Once declared active message can be used as regular model inside controller:

use app\mail\active\ContactUs;

// ...

public function actionContact()
{
    $model = new ContactUs();
    if ($model->load(Yii::$app->request->post()) && $model->send()) {
        Yii::$app->session->setFlash('contactFormSubmitted');
        return $this->refresh();
    }
    return $this->render('contact', [
        'model' => $model,
    ]);
}

[[\yii2tech\activemail\ActiveMessage]] uses regular Yii2 mail composition mechanism based on view files. By default it uses internal view provided by this extension. However in order to work properly it obviously requires layout view to exist. Each particular active message may specify its own view via viewName() method declaration. The most basic content for such view would be following:

<?php
/* @var $this yii\web\View */
/* @var $activeMessage yii2tech\activemail\ActiveMessage */

echo $activeMessage->getBodyHtml();
?>

Working with placeholders

Each part of active message such as subject or body may contain placeholders in format: {placeholderName}. While message composition these placeholders will be replaced by thier actual values. The actual placeholders are defined via templatePlaceholders() method. By default it it uses current active message attribute values, but you may override it in order to add extra placeholders:

public function templatePlaceholders()
{
    return array_merge(
        parent::templatePlaceholders(),
        [
            'nowDate' => date('Y-m-d')
        ]
    );
}

[[\yii2tech\activemail\ActiveMessage]] also declares templatePlaceholderHints() method, which can be used to specify hints for each used placeholder. You may use it, while composing edit form for the mail template.

Template usage

The main benefit of [[\yii2tech\activemail\ActiveMessage]] usage is mail template feature. Each active message can have a named template, which overrides its default values for subject, body etc. The template name is defined via templateName() method. By default the active message class base name is used.

Actual template source is defined via 'mail template storage' component, which has been already mentioned above.

Following template storages are available:

[[\yii2tech\activemail\TemplateStoragePhp]] - stores templates inside PHP files
[[\yii2tech\activemail\TemplateStorageDb]] - stores templates inside relational database
[[\yii2tech\activemail\TemplateStorageMongoDb]] - stores templates inside MongoDB
[[\yii2tech\activemail\TemplateStorageActiveRecord]] - finds templates using ActiveRecord

Please refer to the particular storage class for more details.

For example: assume we use [[\yii2tech\activemail\TemplateStoragePhp]] as template storage. In order to define a template for our app\mail\active\ContactUs active message, we should create a file under '@app/mail/templates' named 'ContactUs.php' with following content:

<?php

return [
    'subject' => 'Override',
    'htmlBody' => 'Override:<br>{message}',
];

After this is done, values from this file for 'subject' and 'htmlBody' will override default ones declared by app\mail\active\ContactUs.

This feature may prove itself very useful, while creating multi-lingual sites. In this case you can declare templateName() method for active message as following:

class ContactUs extends ActiveMessage
{
    // ...

    public function templateName()
    {
        return Yii::$app->language . DIRECTORY_SEPARATOR . 'ContactUs';
    }
}

Then you may create multiple templates named 'ContactUs' under sub-directories, which names matching particular language code like 'en-US', 'de' and so on.

Using database template storages allows application administrator override mail messages content if necessary, by inserting corresponding row into a table and restore default value by deleting it.

Note: templates are meant to override default active message values, thus if particular template is missing in the storage, the program will NOT trigger any error or throw any exception.

Template management

The most common reason of using special mail template system is allowing application administrator to edit them via web interface. In order to simplify such feature creation, this extension provides [[\yii2tech\activemail\TemplateModelFinder]] class, which allows listing all available active messages and created templates. The search model for the active messages can look like following:

use yii\base\Model;
use yii\data\ArrayDataProvider;
use yii2tech\activemail\TemplateModelFinder;
use app\models\MailTemplate;

class MailTemplateSearch extends Model
{
    public $name;
    public $subject;

    public function search()
    {
        // get raw data
        $finder = new TemplateModelFinder([
            'activeRecordClass' => MailTemplate::className();
        ]);
        $models = $finder->findAllTemplateModels();

        // filter list :
        $filterModel = $this;
        $models = array_filter($models, function ($model) use ($filterModel) {
            /* @var $model MailTemplate */
            if (!empty($filterModel->name)) {
                if ($filterModel->name != $model->name) {
                    return false;
                }
            }
            if (!empty($filterModel->subject)) {
                if (strpos($model->subject, $filterModel->subject) === false) {
                    return false;
                }
            }
            return true;
        });

        // compose data provider
        return new ArrayDataProvider([
            'allModels' => $models,
            'sort' => [
                'attributes' => ['name', 'subject'],
            ],
        ]);
    }
}

The web controller for email templates can look like following:

use yii\web\Controller;
use yii\web\NotFoundHttpException;
use Yii;
use app\models\MailTemplate;
use app\models\MailTemplateSearch;

class MailTemplateController extends Controller
{
    public function actionIndex()
    {
        $searchModel = new MailTemplateSearch();
        $dataProvider = $searchModel->search(Yii::$app->request->queryParams);

        return $this->render('index', [
            'searchModel' => $searchModel,
            'dataProvider' => $dataProvider,
        ]);
    }

    public function actionUpdate($name)
    {
        $finder = new TemplateModelFinder([
            'activeRecordClass' => MailTemplate::className();
        ]);

        $model = $finder->findTemplateModel($name);
        if ($model === null) {
            throw new NotFoundHttpException('The requested page does not exist.');
        }

        if ($model->load(Yii::$app->request->post()) && $model->save()) {
            return $this->redirect(['index']);
        }

        return $this->render('update', [
            'model' => $model,
        ]);
    }
}

yii2tech/activemail 适用场景与选型建议

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

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

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

围绕 yii2tech/activemail 我们能提供哪些服务？

定制开发 / 二次开发

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

BUG 修复 & 性能优化

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

项目外包 & 长期维护

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

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

与 yii2tech/activemail 相关的其它包

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

dg/dibi 501

Dibi is Database Abstraction Library for PHP

ismaambrosi/generator-bundle 26

Generates Symfony2 documents, forms and CRUD

novius/laravel-translation-loader 1

Store your language lines in the database, yaml or other sources

fileinvite-org/laravel-database-encryption 0

A package for automatically encrypting and decrypting Eloquent attributes in Laravel 5.5+, based on configuration settings.

beebmx/kirby-courier 40

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

theodorejb/phaster 6

A PSR-7 compatible library for making CRUD API endpoints

yii2tech/activemail

包简介

关键字：