README

PHPMailer – 一个功能齐全的 PHP 邮件创建和传输类

特点

可能是世界上发送电子邮件最流行的 PHP 代码！
被许多开源项目使用：WordPress、Drupal、1CRM、SugarCRM、Yii、Joomla! 以及更多
集成 SMTP 支持 – 无需本地邮件服务器即可发送邮件
使用多个收件人、抄送、暗送和回复地址发送邮件
多部分/替代电子邮件，适用于不支持 HTML 电子邮件的邮件客户端
添加附件，包括内联附件
支持 UTF-8 内容和 8bit、base64、二进制和 quoted-printable 编码
通过 SMTPS 和 SMTP+STARTTLS 传输使用 LOGIN、PLAIN、CRAM-MD5 和 XOAUTH2 机制进行 SMTP 认证
自动验证电子邮件地址
防止头注入攻击
50 多种语言的错误消息！
支持 DKIM 和 S/MIME 签名
兼容 PHP 5.5 及更高版本，包括 PHP 8.2
使用命名空间以避免名称冲突
更多！

为什么你可能需要它

许多 PHP 开发者需要从他们的代码中发送电子邮件。唯一直接支持此功能的 PHP 函数是 mail()。然而，它不提供任何关于使用加密、身份验证、HTML 消息和附件等流行功能的支持。

正确格式化电子邮件实际上非常困难。存在许多重叠（和冲突）的标准，需要严格遵守复杂的格式和编码规则 – 在网上找到的大多数直接使用 mail() 函数的代码都是错误的，甚至是不安全的！

PHP 的 mail() 函数通常通过本地邮件服务器发送，通常在 Linux、BSD 和 macOS 平台上由 sendmail 二进制文件前端，但是 Windows 通常不包括本地邮件服务器；PHPMailer 的集成 SMTP 客户端允许在所有平台上发送电子邮件，无需本地邮件服务器。但是请注意，在可能的情况下应避免使用 mail() 函数；使用 SMTP 到本地主机既快又安全。

请不要被诱惑自己动手做 – 如果你不使用 PHPMailer，在开始自己编写之前，你应该查看许多其他出色的库。尝试 SwiftMailer 、 Laminas/Mail、 ZetaComponents 等。

许可证

此软件根据 LGPL 2.1 许可证以及 GPL 合作承诺进行分发。请阅读 LICENSE 了解有关软件可用性和分发的信息。

安装和加载

PHPMailer可在Packagist上找到（使用语义版本控制），通过Composer安装PHPMailer是推荐的安装方式。只需将以下行添加到您的composer.json文件中

"phpmailer/phpmailer": "^6.9.1"

或者运行

composer require phpmailer/phpmailer

请注意，vendor文件夹和vendor/autoload.php脚本是由Composer生成的；它们不是PHPMailer的一部分。

如果您想使用XOAUTH2身份验证，还需要在您的composer.json中添加对league/oauth2-client和相应的服务适配器包的依赖，或者查看@decomplexity的SendOauth2包装器，尤其是如果您使用的是Microsoft服务。

或者，如果您不使用Composer，可以下载PHPMailer的zip文件（注意，zip文件中不包括文档和示例），然后将PHPMailer文件夹的内容复制到PHP配置中指定的include_path目录之一中，并手动加载每个类文件。

<?php
use PHPMailer\PHPMailer\PHPMailer;
use PHPMailer\PHPMailer\Exception;

require 'path/to/PHPMailer/src/Exception.php';
require 'path/to/PHPMailer/src/PHPMailer.php';
require 'path/to/PHPMailer/src/SMTP.php';

如果您没有明确使用SMTP类（您可能没有），则不需要为SMTP类添加use行。即使您没有使用异常，您仍然需要加载Exception类，因为它在内部使用。

旧版本

PHPMailer 5.2（与PHP 5.0 — 7.0兼容）不再受支持，即使是安全更新。您可以在5.2-stable分支中找到5.2的最新版本。如果您使用的是PHP 5.5或更高版本（您应该使用），请切换到6.x版本。

从5.2升级

最大的变化是源文件现在位于src/文件夹中，PHPMailer现在声明了命名空间PHPMailer\PHPMailer。这有几个重要的影响——阅读升级指南以获取更多详细信息。

最小安装

虽然手动或使用Composer安装整个包很简单、方便且可靠，但您可能只想将项目中的关键文件包含在内。至少您需要src/PHPMailer.php。如果您使用SMTP，则需要src/SMTP.php，如果您使用POP-before SMTP（非常不可能！），则需要src/POP3.php。如果您不向用户显示错误并且可以仅使用英文错误，则可以跳过language文件夹。如果您使用XOAUTH2，还需要src/OAuth.php以及您希望认证的服务的Composer依赖项。实际上，使用Composer要容易得多！

简单示例

<?php
//Import PHPMailer classes into the global namespace
//These must be at the top of your script, not inside a function
use PHPMailer\PHPMailer\PHPMailer;
use PHPMailer\PHPMailer\SMTP;
use PHPMailer\PHPMailer\Exception;

//Load Composer's autoloader
require 'vendor/autoload.php';

//Create an instance; passing `true` enables exceptions
$mail = new PHPMailer(true);

try {
    //Server settings
    $mail->SMTPDebug = SMTP::DEBUG_SERVER;                      //Enable verbose debug output
    $mail->isSMTP();                                            //Send using SMTP
    $mail->Host       = 'smtp.example.com';                     //Set the SMTP server to send through
    $mail->SMTPAuth   = true;                                   //Enable SMTP authentication
    $mail->Username   = 'user@example.com';                     //SMTP username
    $mail->Password   = 'secret';                               //SMTP password
    $mail->SMTPSecure = PHPMailer::ENCRYPTION_SMTPS;            //Enable implicit TLS encryption
    $mail->Port       = 465;                                    //TCP port to connect to; use 587 if you have set `SMTPSecure = PHPMailer::ENCRYPTION_STARTTLS`

    //Recipients
    $mail->setFrom('from@example.com', 'Mailer');
    $mail->addAddress('joe@example.net', 'Joe User');     //Add a recipient
    $mail->addAddress('ellen@example.com');               //Name is optional
    $mail->addReplyTo('info@example.com', 'Information');
    $mail->addCC('cc@example.com');
    $mail->addBCC('bcc@example.com');

    //Attachments
    $mail->addAttachment('/var/tmp/file.tar.gz');         //Add attachments
    $mail->addAttachment('/tmp/image.jpg', 'new.jpg');    //Optional name

    //Content
    $mail->isHTML(true);                                  //Set email format to HTML
    $mail->Subject = 'Here is the subject';
    $mail->Body    = 'This is the HTML message body <b>in bold!</b>';
    $mail->AltBody = 'This is the body in plain text for non-HTML mail clients';

    $mail->send();
    echo 'Message has been sent';
} catch (Exception $e) {
    echo "Message could not be sent. Mailer Error: {$mail->ErrorInfo}";
}

您将在examples文件夹中找到很多可以尝试的内容，它涵盖了许多常见场景，包括通过Gmail发送、构建联系表单、向邮件列表发送等。

如果您正在重用实例（例如，向邮件列表发送时），您可能需要清除收件人列表以避免发送重复的消息。有关进一步指导，请参阅邮件列表示例。

就是这样。您现在应该可以使用PHPMailer了！

本地化

PHPMailer 默认使用英文，但在语言文件夹中，您可以找到许多您可能遇到的 PHPMailer 错误信息的翻译。它们的文件名包含 ISO 639-1 语言代码，例如 fr 代表法语。要指定语言，您需要告诉 PHPMailer 使用哪种语言，如下所示

//To load the French version
$mail->setLanguage('fr', '/optional/path/to/language/directory/');

我们欢迎更正和新语言的支持——如果您正在寻找更正，请在 tests 文件夹中运行 Language/TranslationCompletenessTest.php 脚本，它将显示任何缺失的翻译。

文档

请从 GitHub wiki 开始阅读。如果您遇到问题，请参考故障排除指南，因为它经常更新。

如何在常见场景中使用 PHPMailer 的示例可以在 examples 文件夹中找到。如果您正在寻找一个良好的起点，我们建议您从 Gmail 示例开始。

为了减少 PHPMailer 部署代码的大小，如果您通过 Composer 或通过 GitHub 的 zip 文件下载加载 PHPMailer，则不包括示例，因此您需要克隆 git 仓库或使用上述链接直接访问示例。

完整的生成 API 文档在线可用。

您可以通过在顶级文件夹中运行 phpdoc 来生成完整的 API 级别文档，文档将出现在 docs 文件夹中，尽管您需要安装 PHPDocumentor。您可能会发现单元测试对于如何执行各种操作（如加密）是一个很好的参考。

如果文档没有涵盖您需要的内容，请搜索 Stack Overflow 上的许多问题，在您询问有关“SMTP 错误：无法连接到 SMTP 服务器”的问题之前，请先阅读故障排除指南。

测试

PHPMailer 测试使用 PHPUnit 9，并通过 polyfill 允许 9-style 测试在较旧的 PHPUnit 和 PHP 版本上运行。

如果这个测试没有通过，您能做些什么来帮助吗？

安全性

请负责任地披露发现的任何漏洞——私下向维护者报告安全问题。

请参阅 SECURITY 和 GitHub 上的 PHPMailer 安全通告。

贡献

请将错误报告、建议和拉取请求提交到 GitHub 问题跟踪器。

我们特别关注修复边缘情况、扩展测试覆盖范围和更新翻译。

如果您在文档中发现了错误，或者想添加一些内容，请直接修改 wiki - 任何人都可以编辑它。

如果您之前从PHPMailer迁移到GitHub组织之前进行了git克隆，您需要更新克隆中引用旧GitHub位置的任何远程URL，如下所示：

git remote set-url upstream https://github.com/PHPMailer/PHPMailer.git

请不要再使用SourceForge或Google Code项目；它们已过时，不再维护。

赞助

PHPMailer的开发时间和资源由Smartmessages.net提供，这是世界上唯一以隐私为先的电子邮件营销系统。

捐款非常受欢迎，无论是啤酒🍺、T恤👕还是冷硬现金💰。通过GitHub进行赞助是向PHPMailer维护者和贡献者表示感谢的一种简单便捷的方式——只需点击项目页面上的“赞助”按钮（点击此处）。如果您的公司使用PHPMailer，请考虑参加Tidelift的企业支持计划。

PHPMailer For Enterprise

作为Tidelift订阅的一部分提供。

PHPMailer和其他数千个包的维护者正在与Tidelift合作，为您的应用程序构建所使用的开源包提供商业支持和维护。节省时间，降低风险，提高代码健康，同时支付您使用的确切包的维护者。了解更多。

变更日志

请参阅变更日志。

历史

PHPMailer最初由Brent R. Matzelle于2001年编写，作为一个SourceForge项目。
Marcus Bointon（SF上的coolbru）和Andy Prevost（codeworxtech）于2004年接管了项目。
2010年成为Google Code上的Apache孵化器项目，由Jim Jagielski管理。
Marcus于2008年在GitHub上创建了他的分支。
Jim和Marcus于2013年决定联手，并使用GitHub作为PHPMailer的官方仓库。
PHPMailer于2013年迁移到GitHub上的PHPMailer组织。

从SourceForge迁移以来有什么变化？

SourceForge和Google Code项目的官方继任者。
测试套件。
与GitHub Actions的持续集成。
Composer支持。
公开开发。
额外的语言和语言字符串。
CRAM-MD5身份验证支持。
保留了从原始SourceForge项目的作者、提交和分支的完整仓库历史。

gemini-d / phpmailer

维护者

详情