README

简单 的UTF-8电子邮件发送服务。

有关升级说明，请参阅 UPGRADING.md。

特性

• SMTP客户端支持用户名/密码认证和安全（SSL）套接字。
• 发送符合MIME规范的文本/HTML多部分电子邮件。
• 使用流处理大型附件，实现可预测的、低内存使用。
• 从内存或任何流包装器中获取附件。
• 支持内联（图片）附件。
• 所有类型的收件人字段都支持多个收件人。
• 发送多个电子邮件而无需重新连接。

非特性

一些功能明确定义在此项目范围之外

• 省略了对任意字符集的支持 - 所有现代邮件客户端都支持UTF-8。

• 不支持mail()作为传输方法，因为这个函数的约束与我们的目标冲突 - 主要是因为它不支持流，这意味着整个消息必须适合内存，这会导致不可预测的性能和内存使用。

概述

通过MailService接口抽象了邮件服务实现，该接口依赖于Message模型来定义实际内容。

要发送邮件，只需创建一个Message实例，通过调用各种公共的set/add方法用新的Address和Attachment模型实例填充它，然后调用MailService::send()。

该模型允许UTF-8文本和HTML消息主体的任意组合，以及任何数量的附件。

使用方法

以下示例假设存在一个名为$service的MailService实例 - 后续部分将解释如何配置电子邮件服务。

以下是一个发送带附件的纯文本电子邮件的示例

$message = new Message(
    new Address($email),        // recipient
    new Address("me@test.org"), // sender
    "Hello, Person!",           // subject
    $text                       // plain text message body
);

$message->addAttachment(Attachment::fromFile(__DIR__ . "/awsum/unicorns.gif"));

$service->send($message);

有关其他消息属性的详细信息，请参阅 Message 模型。

SMTP邮件服务

SMTPMailService实现通过套接字直接连接到SMTP服务器。

要启动SMTP邮件服务，您需要选择您的Connector和Authenticator实现 - 例如

$service = new SMTPMailService(
    new SocketConnector("localhost", 25),
    new LoginAuthenticator("user", "super_secret_pa55w0rd"),
    "test.org"
);

注意第三个参数，即本地主机名 - 当客户端连接时，它用于在SMTP服务器上发送握手（EHLO）消息。

支持SMTP协议级别的日志记录，用于诊断目的，可以通过通过SMTPClient::setLogger()将PSR-3 Logger注入到SMTPClient中启用 - 如果您有连接问题，这可能很有用，因为它将为每个发送的SMTP命令和每个接收到的响应写入一个debug级别的条目。

消息日志记录

与上面描述的SMTP协议级别的日志记录不同，还提供了一个更通用的日志记录功能 - 这将在成功或失败发送消息时写入单个日志条目，并更普遍适用于任何MailService实现，包括当然SMTP服务。

要向PSR-3 Logger写入日志条目，请使用MailSeviceLogger实现，它作为任何其他MailService实现的装饰器 - 例如

$service = new MailServiceLogger($psr_logger, new SMTPMailService(...));

有关自定义消息模板和日志级别的详细信息，请参阅MailServiceLogger的内置文档。

被动邮件服务

提供了一个被动实现MailService，它不执行任何操作。

您可以在测试/开发过程中使用此功能来禁用任何发送消息。

这通常与上面描述的MailServiceLogger一起使用最有用，以启动一个用于测试和开发的假邮件服务，使您能够看到本应发送的消息。

开发

要运行集成测试，您需要设置一个用于测试的本地SMTP服务器。

为了确保SecureSocketCest通过，您的SMTP服务器也需要支持TLS，并拥有SSL证书。

建议使用smtp4dev，因为它具有跨平台支持，可以生成自己的自签名SSL证书。

在配置smtp4dev时，请确保将TlsMode设置为StartTls，这确保了只有在客户端请求时才使用TLS，将设置改为ImplicitTls可能会使所有非TLS测试失败。

当启动smtp4dev服务器时，它应该告诉您生成的证书存储位置，您需要将此添加到您的系统受信任的CA存储库中。

您可能需要将integration.suite.dist.yml复制到integration.suite.yml以自定义SMTP主机名、端口号等。

目标

此库有几个明确的设计目标

• 简洁性：UTF-8是唯一支持的字符集，我们努力不重复造轮子（例如，利用base64和quoted-printable流过滤器），并且库没有外部依赖。
• 使用流以提高效率和可预测的内存使用 - 尤其是文件附件以块的形式编码和发送，而不需要缓冲整个消息或处理巨大的字符串。
• 关注点的分离 - 尤其是MIME编码和SMTP传输关注点（"点填充"）完全分离，这又通过正确使用流得以实现。
• 在所有地方使用依赖注入（主要是构造函数注入）。
• 在高级和依赖/组件级别都使用抽象（接口）。