包简介

JDZ mailer

README 文档

README

Flexible PHP mailer with SMTP (via PHPMailer), Mailchimp Transactional, and native mail() support. Automatic fallback between senders, HTML/plain-text content handling, DKIM signing, and attachments.

Installation

composer require jdz/mailer

Optional senders (install as needed):

composer require phpmailer/phpmailer        # SMTP / DKIM / Sendmail
composer require mailchimp/transactional     # Mailchimp Transactional API

Optional HTML-to-text converters for the alternative body:

composer require ph-7/html-to-text           # PH7 converter
composer require soundasleep/html2text       # Soundasleep converter

Requirements

PHP >= 8.2

Configuration

Copy .env.dist to .env and fill in your credentials:

cp .env.dist .env

The .env file is gitignored and never committed.

Usage

SMTP Email

use Symfony\Component\Dotenv\Dotenv;
use JDZ\Mailer\Mailer;
use JDZ\Mailer\AltBody\BasicAltBody;

(new Dotenv())->loadEnv(__DIR__ . '/.env');

$mail = new Mailer();

$mail->setProperties([
    'domain' => 'example.com',
    'language' => 'fr',
    'charset' => 'utf-8',
]);

$mail->setContent([
    'isHtml' => true,
    'content' => '<h1>Hello</h1><p>This is a test email.</p>',
    'template' => '<html><body>{{BODY}}</body></html>',
    'altBodyFormatter' => new BasicAltBody(),
]);

$mail->setSMTP([
    'host' => $_ENV['SMTP_HOST'],
    'port' => (int)$_ENV['SMTP_PORT'],
    'secure' => $_ENV['SMTP_SECURE'],
    'auth' => true,
    'user' => $_ENV['SMTP_USER'],
    'pass' => $_ENV['SMTP_PASS'],
]);

$mail->setFrom($_ENV['MAIL_FROM_EMAIL'], $_ENV['MAIL_FROM_NAME']);
$mail->addRecipient('recipient@example.com', 'Recipient');
$mail->set('subject', 'Hello from JDZ Mailer');

$mail->send();

Mailchimp Transactional

$mail = new Mailer();

$mail->setContent([
    'isHtml' => true,
    'content' => '<p>Newsletter content</p>',
    'altBodyFormatter' => new BasicAltBody(),
]);

$mail->setMailchimp([
    'apiKey' => $_ENV['MAILCHIMP_API_KEY'],
    'track_opens' => true,
    'track_clicks' => true,
]);

$mail->addRecipient('subscriber@example.com', 'Subscriber');
$mail->set('subject', 'Monthly Newsletter');
$mail->send();

Native mail()

If no SMTP or Mailchimp is configured, the mailer falls back to PHP's native mail() function:

$mail = new Mailer();
$mail->domain = 'example.com';
$mail->setFrom('sender@example.com', 'Sender');
$mail->addRecipient('recipient@example.com');
$mail->set('subject', 'Simple email');
$mail->content->setProperties([
    'content' => 'Plain text message',
    'altBodyFormatter' => new BasicAltBody(),
]);
$mail->send();

Fallback

Enable useFallback to automatically fall back to a simpler sender if the preferred one is unavailable:

$mail->useFallback = true;  // mailchimp -> smtp -> mail()

Recipients

$mail->addRecipient('to@example.com', 'To');
$mail->addCc('cc@example.com', 'CC');
$mail->addBcc('bcc@example.com', 'BCC');
$mail->addReplyTo('reply@example.com', 'Reply To');

// Or bulk:
$mail->addRecipients([
    ['email' => 'alice@example.com', 'name' => 'Alice'],
    ['email' => 'bob@example.com', 'name' => 'Bob'],
]);

// No-reply (prevents further addReplyTo calls):
$mail->setNoReply('noreply@example.com');

Attachments

$mail->addAttachment('/path/to/file.pdf', 'report.pdf', 'base64', 'application/pdf');

Content Replacements

$mail->setContent([
    'isHtml' => true,
    'content' => '<p>Hello {{NAME}}, your order #{{ORDER}} is ready.</p>',
    'replacements' => [
        '{{NAME}}' => 'John',
        '{{ORDER}}' => '12345',
    ],
    'altBodyFormatter' => new BasicAltBody(),
]);

Template-Only Mode

Use a full template without separate content:

$mail->setContent([
    'templateOnly' => true,
    'template' => '<html><body><h1>Full HTML template</h1></body></html>',
    'altBodyFormatter' => new BasicAltBody(),
]);

Alt Body Formatters

Three HTML-to-plain-text converters are available:

BasicAltBody - Built-in, uses strip_tags() (no extra dependency)
Ph7AltBody - Uses ph-7/html-to-text
SoundasleepAltBody - Uses soundasleep/html2text

Exceptions

ConfigException - Invalid configuration (missing fields, bad values)
SmtpException - SMTP send failure
MailchimpException - Mailchimp API failure
Exception - General mailer errors

try {
    $mail->send();
} catch (\JDZ\Mailer\Exception\ConfigException $e) {
    // Bad configuration
} catch (\JDZ\Mailer\Exception\SmtpException $e) {
    // SMTP error
} catch (\JDZ\Mailer\Exception\MailchimpException $e) {
    // Mailchimp error
} catch (\JDZ\Mailer\Exception\Exception $e) {
    // General error
}

Testing

composer test
# or
vendor/bin/phpunit

License

This project is licensed under the MIT License - see the LICENSE file for details.

jdz/mailer 适用场景与选型建议

jdz/mailer 是一款基于 PHP 开发的 Composer 扩展包，目前已累计 51 次下载、GitHub Stars 达 0，最近一次更新时间为 2024 年 12 月 13 日，在 PHP 生态内属于活跃度较高的组件。

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

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

围绕 jdz/mailer 我们能提供哪些服务？

定制开发 / 二次开发

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

BUG 修复 & 性能优化

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

项目外包 & 长期维护

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

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

与 jdz/mailer 相关的其它包

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

behat/environment-loader 0

Environment processor and contexts autoloader

tnw/soap-client 0

A PHP client for the Salesforce SOAP API

anthonymartin/aws_acl_fail2ban 34

This package includes a script and fail2ban configuration that allows you to use fail2ban when utilizing AWS elastic load balancer (ELB) and an apache webserver.

logicbrush/silverstripe-userforms-utils 2

A collection of enhancements and utilities for the Silverstripe UserForms module

jkujawski/laravel-sare-mailer 1

Creates new sare mail transport for laravel applications

beyerz/aws-queue-bundle 2

Symfony bundle to connect AWS sns and sqs to create offline queue processing

jdz/mailer

包简介

关键字：