跳转至

Yii

适用于 Yii 2（2.0.43+）应用的集成指南。Mailexam 通过 mailer 组件及 yii2-symfonymailer 扩展作为 SMTP 服务器接入。

前置条件

  • Mailexam 账户，以及已创建并具备 SMTP 凭据的项目。
  • Yii 2（Basic 或 Advanced 模板）。

从项目的欢迎邮件（或控制台）中复制：

  • YOUR_LOGIN — SMTP 登录名（例如 xxxxx）；
  • YOUR_PASSWORD — SMTP 密码（与登录名成对的唯一凭据）；
  • 主机 — YOUR_LOGIN.mailexam.cn（与登录名一致）。

1. 依赖

composer require yiisoft/yii2-symfonymailer
composer require vlucas/phpdotenv  # 本地开发使用 .env

composer.json 应包含 yiisoft/yii2-symfonymailer，必要时包含 vlucas/phpdotenv。

2. 环境变量

项目根目录的 .env 文件（加入 .gitignore）：

MAILEXAM_LOGIN=YOUR_LOGIN
MAILEXAM_PASSWORD=YOUR_PASSWORD
MAILEXAM_PORT=587
MAIL_FROM=noreply@example.test

在启动时加载 .env（例如在创建应用前的 web/index.php 和 yii 中）：

Dotenv\Dotenv::createImmutable(__DIR__ . '/..')->safeLoad();

配置中的主机：YOUR_LOGIN.mailexam.cn。

发件人地址

MAIL_FROM 可以是任意测试地址——邮件进入 Mailexam，而非真实收件人。

备选端口

MAILEXAM_PORT=587

MAILEXAM_PORT=2525

MAILEXAM_PORT=25

3. mailer 组件

config/web.php（或共享的 config/main.php）片段：

<?php

$login = getenv('MAILEXAM_LOGIN') ?: '';
$port = (int) (getenv('MAILEXAM_PORT') ?: 587);

return [
    // ...
    'components' => [
        'mailer' => [
            'class' => \yii\symfonymailer\Mailer::class,
            'useFileTransport' => false,
            'transport' => [
                'scheme' => 'smtp',
                'host' => $login . '.mailexam.cn',
                'username' => $login,
                'password' => getenv('MAILEXAM_PASSWORD') ?: '',
                'port' => $port,
            ],
        ],
    ],
];

Advanced 模板请将相同配置写入 common/config/main-local.php。

确保 useFileTransport 为 false；否则邮件会写入文件而非通过 SMTP 发送。

4. 发送测试邮件

通过控制台

// commands/MailController.php
namespace app\commands;

use Yii;
use yii\console\Controller;

class MailController extends Controller
{
    public function actionTest(): int
    {
        $from = getenv('MAIL_FROM') ?: 'noreply@example.test';

        $sent = Yii::$app->mailer->compose()
            ->setFrom([$from => 'Mailexam 测试'])
            ->setTo('user@example.test')
            ->setSubject('Yii + Mailexam')
            ->setTextBody('来自 Yii 的 Mailexam 测试')
            ->send();

        $this->stdout($sent ? "ok\n" : "error\n");
        return $sent ? self::EXIT_CODE_NORMAL : self::EXIT_CODE_ERROR;
    }
}

php yii mail/test

通过 HTTP（控制器）

// controllers/MailController.php
namespace app\controllers;

use Yii;
use yii\web\Controller;
use yii\web\Response;

class MailController extends Controller
{
    public function actionTest(): array
    {
        Yii::$app->response->format = Response::FORMAT_JSON;

        $from = getenv('MAIL_FROM') ?: 'noreply@example.test';

        Yii::$app->mailer->compose()
            ->setFrom([$from => 'Mailexam 测试'])
            ->setTo('user@example.test')
            ->setSubject('Yii + Mailexam')
            ->setTextBody('来自 Yii 的 Mailexam 测试')
            ->send();

        return ['status' => 'ok'];
    }
}

在 urlManager 中添加规则，在浏览器中打开路由或用 curl 调用。

邮件将出现在 Mailexam 控制台 → 您的项目 → 收件箱。

5. 本地开发与 CI

环境 建议
local .env 或带 Mailexam 凭据的 *-local.php
CI 流水线密钥中的 MAILEXAM_LOGIN、MAILEXAM_PASSWORD

GitLab CI 示例：

variables:
  MAILEXAM_LOGIN: $MAILEXAM_LOGIN
  MAILEXAM_PASSWORD: $MAILEXAM_PASSWORD
  MAILEXAM_PORT: "587"
  MAIL_FROM: "noreply@example.test"

流水线发送邮件后，通过 Mailexam API 验证投递。

6. 常见问题

邮件未发送，runtime/mail 中有文件

  • 检查 mailer 配置中 useFileTransport => false。

TLS 或连接错误

  • host 须为 {login}.mailexam.cn，username 为邮件中的同一登录名。
  • 登录名和密码为同一项目的邮件成对凭据。

环境变量为空

  • 在 new yii\web\Application($config) 之前调用 Dotenv::createImmutable(...)->safeLoad()。
  • 生产环境在 PHP-FPM / 容器环境中设置变量。

控制台中看不到邮件

  • 查看同一 Mailexam 项目的收件箱。
  • 必要时启用调试：Yii::debug(Yii::$app->mailer->transport)。

参见