README

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

构建状态：

类功能

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

为什么你可能需要它

许多 PHP 开发者会在他们的代码中使用电子邮件。唯一支持此功能的 PHP 函数是 mail() 函数。然而，它不提供任何使用 HTML 基于电子邮件和附件等流行功能的帮助。

正确格式化电子邮件竟然如此困难。存在众多重叠的 RFC，需要严格遵循复杂的格式化和编码规则——你将在网上找到的几乎所有直接使用 mail() 函数的代码都是错误的！请不要尝试自己实现——如果你不使用 PHPMailer，还有许多其他出色的库你应该在尝试自己实现之前查看——尝试 SwiftMailer、Zend_Mail、eZcomponents 等。

PHP 的 mail() 函数通常通过本地邮件服务器发送，通常在 Linux、BSD 和 OS X 平台上由 sendmail 二进制文件提供前端，然而 Windows 通常不包含本地邮件服务器；PHPMailer 的集成 SMTP 实现允许在 Windows 平台上发送电子邮件而无需本地邮件服务器。

许可证

本软件根据 LGPL 2.1 许可证分发。请阅读 LICENSE 以了解软件可用性和分发信息。

安装与加载

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

"phpmailer/phpmailer": "~6.0"

或运行

composer require phpmailer/phpmailer

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

如果您想使用Gmail XOAUTH2认证类，您还需要在您的composer.json文件中添加对league/oauth2-client包的依赖。

或者，如果您没有使用composer，可以将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行。

如果您不懂git或者只想获取tarball，请点击GitHub项目页面右侧的'zip'按钮，但请注意，tarball中不包含文档和示例。

从5.2升级

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

旧版本

PHPMailer 5.2（与PHP 5.0 - 7.0兼容）不再提供功能更新支持，现在只接收安全更新。您可以在5.2-stable分支中找到5.2的最新版本，5.2的未来版本将被标记为5.2.x版本号，因此现有的composer配置应该仍然可以正常工作。如果您使用的是PHP 5.5或更高版本，我们建议您进行必要的更改以切换到6.0版本。

最小安装

虽然手动或使用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\Exception;

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

$mail = new PHPMailer(true);                              // Passing `true` enables exceptions
try {
    //Server settings
    $mail->SMTPDebug = 2;                                 // Enable verbose debug output
    $mail->isSMTP();                                      // Set mailer to use SMTP
    $mail->Host = 'smtp1.example.com;smtp2.example.com';  // Specify main and backup SMTP servers
    $mail->SMTPAuth = true;                               // Enable SMTP authentication
    $mail->Username = 'user@example.com';                 // SMTP username
    $mail->Password = 'secret';                           // SMTP password
    $mail->SMTPSecure = 'tls';                            // Enable TLS encryption, `ssl` also accepted
    $mail->Port = 587;                                    // TCP port to connect to

    //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.';
    echo 'Mailer Error: ' . $mail->ErrorInfo;
}

您将在examples文件夹中找到更多可以玩耍的内容。

就这样。现在您应该准备好使用PHPMailer了！

本地化

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

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

我们欢迎更正和新语言 - 如果您正在寻找要做的更正，请在测试文件夹中运行PHPMailerLangTest.php脚本，它将显示任何缺少的翻译。

文档

开始阅读GitHub wiki（[GitHub wiki](https://github.com/PHPMailer/PHPMailer/wiki)）。如果您遇到问题，这是您应该首先查看的地方，因为它是最经常更新的。

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

请注意，为了减少PHPMailer的部署代码占用空间，如果您通过composer或通过GitHub的zip文件下载加载PHPMailer，示例将不再包含在内，因此您需要克隆git仓库或使用上述链接直接获取示例。

完整的生成API文档在线可用（[在线文档](http://phpmailer.github.io/PHPMailer/)）。

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

如果文档没有涵盖您所需的内容，请在Stack Overflow上的许多问题中进行搜索，并且在您询问有关"SMTP错误：无法连接到SMTP主机"的问题之前，请阅读故障排除指南。

测试

在test文件夹中有一个PHPUnit测试脚本。PHPMailer使用PHPUnit 4.8 - 我们会使用5.x，但我们需要在PHP 5.5上运行。

构建状态：

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

安全

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

PHPMailer版本低于5.2.22（2017年1月9日发布）存在本地文件泄露漏洞，CVE-2017-5223。如果传递给msgHTML()的内容来源于未经过滤的用户输入，则相对路径可以映射到绝对本地文件路径并作为附件添加。请注意，addAttachment（就像file_get_contents、passthru、unlink等）也不应传递用户输入的参数！由Asiasecurity的Yongxiang Li报告。

PHPMailer版本低于5.2.20（2016年12月28日发布）存在CVE-2016-10045远程代码执行漏洞，由Dawid Golunski负责报告，并由Paul Buonopane（@Zenexer）修复。

PHPMailer版本低于5.2.18（2016年12月发布）存在CVE-2016-10033严重远程代码执行漏洞，由Dawid Golunski负责报告。

有关安全问题的更多详细信息，请参阅SECURITY。

贡献

请将错误报告、建议和拉取请求提交到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恤👕、亚马逊愿望清单突袭，还是冷酷的现金💰。如果你想向维护者或贡献者捐赠以表示感谢，请通过贡献者页面通过他们的个人资料页面联系他们。

变更日志

请参阅变更日志。

历史

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

从SourceForge迁移后发生了什么变化？

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

fatfishdigital / phpmailer

维护者

详细信息