跳转至

Phalcon

适用于 Phalcon 5.x（PHP）应用的集成指南。Mailexam 通过 phalcon/incubator-mailer 包（PHPMailer 封装）作为 SMTP 接入。

前置条件

  • Mailexam 账户，以及已创建并具备 SMTP 凭据的项目。
  • PHP 8.1+ 及已安装的 Phalcon 扩展。
  • Phalcon 项目（MVC）及 Composer。

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

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

1. 依赖

composer require phalcon/incubator-mailer
composer require vlucas/phpdotenv

确认扩展已加载：

php -m | grep phalcon

2. 环境变量

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

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

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

Dotenv\Dotenv::createImmutable(BASE_PATH)->safeLoad();

SMTP 主机：YOUR_LOGIN.mailexam.cn。

发件人地址

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

备选端口

MAILEXAM_PORT=587

邮件配置中：'encryption' => 'tls'。

MAILEXAM_PORT=2525

'encryption' => 'tls'。

MAILEXAM_PORT=465

'encryption' => 'ssl'。

MAILEXAM_PORT=25

移除 encryption 键或设为空字符串。

3. SMTP 配置

app/Services/MailConfig.php：

<?php

declare(strict_types=1);

namespace App\Services;

final class MailConfig
{
    public static function smtp(): array
    {
        $login = getenv('MAILEXAM_LOGIN') ?: '';
        $port = (int) (getenv('MAILEXAM_PORT') ?: 587);
        $from = getenv('MAIL_FROM') ?: 'noreply@example.test';

        $config = [
            'driver'     => 'smtp',
            'host'       => $login . '.mailexam.cn',
            'port'       => $port,
            'username'   => $login,
            'password'   => getenv('MAILEXAM_PASSWORD') ?: '',
            'from'       => [
                'email' => $from,
                'name'  => 'Mailexam 测试',
            ],
        ];

        if ($port === 465) {
            $config['encryption'] = 'ssl';
        } elseif (in_array($port, [587, 2525], true)) {
            $config['encryption'] = 'tls';
        }

        return $config;
    }
}

4. 发送测试邮件

app/Controllers/MailController.php：

<?php

declare(strict_types=1);

namespace App\Controllers;

use App\Services\MailConfig;
use Phalcon\Incubator\Mailer\Manager as MailerManager;
use Phalcon\Mvc\Controller;

class MailController extends Controller
{
    public function testAction()
    {
        $this->view->disable();
        $this->response->setContentType('application/json', 'UTF-8');

        $payload = $this->request->getJsonRawBody(true) ?? [];

        $to = $payload['to'] ?? 'user@example.test';
        $subject = $payload['subject'] ?? 'Phalcon + Mailexam';
        $body = $payload['body'] ?? '来自 Phalcon 的 Mailexam 测试';

        $mailer = new MailerManager(MailConfig::smtp());

        $mailer->createMessage()
            ->to($to)
            ->subject($subject)
            ->content($body)
            ->send();

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

config/routes.php 中的路由：

<?php

use Phalcon\Mvc\Router;

$router = new Router(false);
$router->setDefaults([
    'namespace'  => 'App\Controllers',
    'controller' => 'index',
    'action'     => 'index',
]);

$router->addPost('/mail/test', [
    'controller' => 'mail',
    'action'     => 'test',
]);

return $router;

启动并验证（PHP 内置服务器或您的虚拟主机）：

php -S 127.0.0.1:8080 -t public

curl -X POST http://127.0.0.1:8080/mail/test \
  -H 'Content-Type: application/json' \
  -d '{"to":"user@example.test","subject":"测试","body":"你好"}'

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

5. 本地开发与 CI

环境 建议
local .env + Dotenv::safeLoad()
CI GitLab CI/CD Variables 中的密钥 MAILEXAM_LOGIN、MAILEXAM_PASSWORD；带 phalcon 扩展的 PHP 镜像

.gitlab-ci.yml 示例：

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

集成测试后，通过 Mailexam API 验证投递。

6. 常见问题

找不到类 'Phalcon...'

  • 为 CLI 和 FPM 使用的同一 PHP 版本安装并启用 Phalcon 扩展。

TLS 或认证失败

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

587 端口

  • 需要 'encryption' => 'tls'，而非 ssl。

控制台中看不到邮件

  • 查看同一 Mailexam 项目的收件箱。
  • 必要时在 incubator-mailer 配置中启用 PHPMailer 调试。

参见