Symfony¶

适用于 Symfony 6.4 / 7.x 应用的集成指南。Mailexam 通过 Symfony Mailer 及 .env 中的 smtp:// DSN 接入。

前置条件¶

Mailexam 账户，以及已创建并具备 SMTP 凭据的项目。
Symfony 应用（Skeleton 或 Webapp）。

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

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

1. 依赖¶

若尚未安装 Mailer：

composer require symfony/mailer

Symfony Webapp 模板通常已包含该包。

2. 环境变量¶

.env 文件（或 .env.local；勿提交密钥）：

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

###> symfony/mailer ###
MAILER_DSN=smtp://${MAILEXAM_LOGIN}:${MAILEXAM_PASSWORD}@${MAILEXAM_LOGIN}.mailexam.cn:${MAILEXAM_PORT}
###< symfony/mailer ###

DSN 中的主机 — YOUR_LOGIN.mailexam.cn，登录名和密码 — 来自邮件。

发件人地址

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

密码中的特殊字符

若密码包含 @、:、/或其他 DSN 字符，请对密码进行 URL 编码（rawurlencode），或在.env.local中手动设置单行MAILER_DSN`。

备选端口¶

587 + STARTTLS（推荐）252525，无 TLS

MAILEXAM_PORT=587

MAILEXAM_PORT=2525

MAILEXAM_PORT=25

3. Mailer 配置¶

config/packages/mailer.yaml 文件（Flex 自动创建）：

framework:
    mailer:
        dsn: '%env(MAILER_DSN)%'

Mailexam 无需额外传输配置。

4. 发送测试邮件¶

通过控制器¶

// src/Controller/MailController.php
namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\Mailer\MailerInterface;
use Symfony\Component\Mime\Email;
use Symfony\Component\Routing\Attribute\Route;

final class MailController extends AbstractController
{
    #[Route('/mail/test', name: 'mail_test', methods: ['POST'])]
    public function test(MailerInterface $mailer): JsonResponse
    {
        $from = $_ENV['MAIL_FROM'] ?? 'noreply@example.test';

        $mailer->send(
            (new Email())
                ->from($from)
                ->to('user@example.test')
                ->subject('Symfony + Mailexam')
                ->text('来自 Symfony 的 Mailexam 测试')
        );

        return $this->json(['status' => 'ok']);
    }
}

启动并验证：

symfony server:start
# 或：php -S 127.0.0.1:8000 -t public

curl -X POST http://127.0.0.1:8000/mail/test

通过控制台¶

php bin/console mailer:test user@example.test --from=noreply@example.test

（已安装 symfony/mailer 且配置 DSN 后可用。）

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

5. 本地开发与 CI¶

环境	建议
`local`	`.env.local` 中的 `MAILER_DSN`
CI	密钥 `MAILEXAM_LOGIN`、`MAILEXAM_PASSWORD`；在作业中构建 `MAILER_DSN`

GitLab CI 示例：

variables:
  MAILEXAM_LOGIN: $MAILEXAM_LOGIN
  MAILEXAM_PASSWORD: $MAILEXAM_PASSWORD
  MAILEXAM_PORT: "587"
  MAIL_FROM: "noreply@example.test"
  MAILER_DSN: "smtp://${MAILEXAM_LOGIN}:${MAILEXAM_PASSWORD}@${MAILEXAM_LOGIN}.mailexam.cn:587"

无需真实发送的单元测试，在 config/packages/test/mailer.yaml 中：

framework:
    mailer:
        dsn: 'null://null'

6. 常见问题¶

认证失败 / 连接被拒绝

检查 MAILER_DSN：主机 {login}.mailexam.cn，登录名和密码 — 邮件中的成对凭据。
DSN 用户 URL 中的登录名须与主机子域名一致。

密码字符导致错误

在 DSN 中对密码使用 rawurlencode，或在 .env.local 中手动设置完整 DSN 字符串。

控制台中看不到邮件

确认 test 环境未覆盖为 null://null 传输。
查看同一 Mailexam 项目的收件箱。

配置缓存

修改 .env 后：php bin/console cache:clear。