PHPackages                             yii2tech/activemail - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Database & ORM](/categories/database)
4. /
5. yii2tech/activemail

AbandonedArchivedYii2-extension[Database & ORM](/categories/database)

yii2tech/activemail
===================

Project installation support extension for the Yii2 framework

1.0.0(9y ago)178.2k9BSD-3-ClausePHP

Since Apr 24Pushed 6y ago1 watchersCompare

[ Source](https://github.com/yii2tech/activemail)[ Packagist](https://packagist.org/packages/yii2tech/activemail)[ RSS](/packages/yii2tech-activemail/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependencies (1)Versions (2)Used By (0)

 [ ![](https://avatars2.githubusercontent.com/u/12951949) ](https://github.com/yii2tech)

ActiveMail Extension for Yii 2
==============================

[](#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](LICENSE.md)-file.

[![Latest Stable Version](https://camo.githubusercontent.com/fd833d5ef7a88265bbd92c18fe898c200fb6f12748d0191588830eb9d55e7e65/68747470733a2f2f706f7365722e707567782e6f72672f79696932746563682f6163746976656d61696c2f762f737461626c652e706e67)](https://packagist.org/packages/yii2tech/activemail)[![Total Downloads](https://camo.githubusercontent.com/a3eb9bec5c5f28b702bfe6d22df850166190e90670029f3aa9b516d8700ef19b/68747470733a2f2f706f7365722e707567782e6f72672f79696932746563682f6163746976656d61696c2f646f776e6c6f6164732e706e67)](https://packagist.org/packages/yii2tech/activemail)[![Build Status](https://camo.githubusercontent.com/ce64fab963f56eedc7bfb76e6872a66d20789198388e360cf845a553b5c19c70/68747470733a2f2f7472617669732d63692e6f72672f79696932746563682f6163746976656d61696c2e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/yii2tech/activemail)

Requirements
------------

[](#requirements)

This extension requires any implementation of the Yii2 mailer, such as [yiisoft/yii2-swiftmailer](https://github.com/yiisoft/yii2-swiftmailer).

Installation
------------

[](#installation)

The preferred way to install this extension is through [composer](http://getcomposer.org/download/).

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
-----

[](#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
--------------

[](#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 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:

```

```

Working with placeholders
--------------------------

[](#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
---------------

[](#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:

```