README

uSend 是一个帮助您处理联系表单的工具：它执行输入数据验证并发送电子邮件。所有这些都通过简单的配置文件和一个或两个模板来控制。

安装

使用 Composer 安装 uSend

composer require umbraprojekt/usend

然后，在您的项目中，如果尚未这样做，请要求Composer的自动加载器

<?php
require_once "../vendor/autoload.php";

使用 uSend

实例化

uSend 的整个理念是尽可能简化验证表单和发送电子邮件的过程。所有操作都使用两个配置文件（或数组，或它们的混合），JSON 或 YAML 完成。库的主要对象还需要您传递 uSend 的依赖注入容器的一个实例。实例化方式如下

<?php
use UmbraProjekt\uSend\Contact;
use UmbraProjekt\uSend\Dic;
use UmbraProjekt\uSend\Config\Yaml;

$uSend = new Contact(
    new Dic(),
    new Yaml("/path/to/transport.yml"),
    new Yaml("/path/to/config.yml"),
    "/path/to/templates"
);

第一个配置文件或数组包含传输数据。传输数据告诉 uSend 使用哪种邮件传输方法：PHP 的 mail() 函数、UNIX sendmail 命令或 SMTP。第二个配置包含用户输入验证和电子邮件配置（需要发送哪些邮件，邮件内容和头信息）。

最后，最后一个参数是可选的，它包含配置文件中定义的模板文件的基路径。如果模板路径是绝对路径，则不是必需的。

执行验证和发送电子邮件

验证和邮件发送在幕后进行，对开发者来说是透明的（前提是传递了配置）。这是通过调用 Contact 实例的 run() 方法并传递用户输入数据来完成的

<?php
$input = json_decode(file_get_contents("php://input"), true);
$input["ip"] = $_SERVER["CLIENT_ADDR"]; // we add data!

$result = $uSend->run($input);

返回的结果是一个包含两个索引的数组

• success - 一个布尔值，指示验证是否成功以及邮件是否已发送
• errors - 验证错误数组

验证错误将是一个关联数组，其中验证的字段名称包含返回无效结果的验证器名称数组。例如，如果 message 字段有一个返回无效结果的 StringLength 验证器（例如，消息太短），则响应可能如下所示

<?php
[
    "success" => true,
    "errors" => [
        "message" => [
            "StringLength"
        ]
    ]
]

配置对象

配置可以以多种方式传递给配置对象，具体取决于您的个人喜好。

PhpArray

这是向 uSend 引入配置的最简单方法，但也是最不灵活的，因为配置需要直接在代码中存在。

<?php
use UmbraProjekt\uSend\Config\PhpArray;

$config = new PhpArray([
    "foo" => "bar"
]);

Yaml

为了创建配置对象，传递它 yml 配置文件的路径

<?php
use UmbraProjekt\uSend\Config\Yaml;

$config = new Yaml("/path/to/config.yml");

Json

类似于 Yaml，只需要传递它 json 配置文件的路径

<?php
use UmbraProjekt\uSend\Config\Json;

$config = new Json("/path/to/config.json");

传输配置

传输配置文件的外观可能因所使用的邮件传输方式而异。在 mail 和 sendmail 传输的情况下，配置文件通常如下所示

transport: mail

或

transport: sendmail

在 SMTP 的情况下，配置可能更长，包含一些额外的选项。

mail

mail 传输具有一个额外的可选参数：extraParams。这些是传递给 mail() 函数的额外参数（它的第五个参数）。

示例 YAML 配置

transport: mail
extraParams: "-f%s"

sendmail

与 mail 类似，sendmail 配置没有或只有最少的额外选项。只有一个额外的参数，这是完全可选的：command。它包含用于发送电子邮件要执行的命令。

示例 YAML 配置

transport: sendmail
command: "/usr/bin/sendmail -bs"

SMTP

SMTP 提供了最多的配置选项。以下是可以用的选项

• host - 发送邮件的邮件服务器。默认为 localhost
• password - 发送邮件的用户的密码
• port - 与主机通信时使用的端口。默认为 25
• encryption - 加密类型（ssl、tls等）。默认不加密
• username - 发送邮件的用户的用户名

示例 YAML 配置

transport: smtp
host: smtp.google.com
port: 487
encryption: ssl
username: user@gmail.com
password: superSecretPassword

邮件配置

邮件配置包含两个主要部分：validation 和 email。

验证

验证配置将验证器分配给表单字段。假设表单发送三个字段：name、email 和 message，验证可能包括每个这些字段的部分。

每个验证字段都依次有验证器名称的键。键对应于 Zend 框架包中的验证器。最常用的大概是 NotEmpty、StringLength 和 EmailAddress。

每个验证器都需要进行配置。当不需要传递配置时，只需留出键无值。否则，值是一个与传递给验证器构造函数的数组完全对应的对象。

示例 YAML 配置

validation:
    name:
        NotEmpty:
    email:
        EmailAddress:
    message:
        StringLength:
            min: 15

上面的配置将验证三个字段（当然，可能还有其他不必要验证的字段）并使用三个验证器：默认配置的 NotEmpty 验证器、也具有默认配置的 EmailAddress，以及最后是 StringLength，它将传递一个包含键 min 和值 15 的数组，创建一个检查用户输入的 message 键是否至少有 15 个字符的验证器。请参阅 Zend 框架的验证器包以获取有关可用验证器和它们配置的信息。

邮件

邮件配置包含一个消息数组，如果验证通过（或根本不需要验证），则将发送这些消息。在每一键下，可以定义多个字段（并非所有都是必需的），这些字段对应于电子邮件正文、标题或附加选项。请注意，此处声明的所有字段都被视为 Twig 模板，因此可以使用 Twig 语法来转义用户输入的字段并使用过滤器。例如，如果您决定向填写联系表单的人发送确认消息，您可以配置他们的电子邮件地址为他们在联系表单中提供的任何地址

to: "{{ email }}"

此外，请注意，除了可由 Twig 解析的字符串外，还可以指定一个指向 Twig 模板文件的路径。在这种情况下，您需要提供绝对路径或相对于模板根目录的路径，该路径提供给 UmbraProjekt\uSend\Contact 对象的构造函数

body: my_awesome_template.twig

每个电子邮件可用的字段如下

• body - 消息的文本正文
• bcc - 消息的 BCC 地址或地址
• bodyHtml - 消息的 HTML 正文
• cc - 消息的 CC 地址或地址
• from - 发送消息的地址或地址
• replyTo - 用于回复电子邮件的地址
• subject - 消息的主题
• to - 消息的收件人或收件人

可用的附加选项

• disableAttachments - 用于阻止与给定消息一起发送附件的标志

定义电子邮件地址

在 from、to、replyTo、cc 和 bcc 字段中的电子邮件地址可以以多种方式定义。

每个电子邮件可以是只包含地址的字符串或包含两个必填字段（name 和 email）的对象

from: "noreply@example.com"
to: { name: John Doe, email: "recipient@example.com" }
replyTo: { name: "{{ name }}", email: "{{ email }}" }

如果有多个地址，则定义为一个数组。同样，数组中的每个项目可以是字符串或对象

to:
    - { name: John Doe, email: "recipient@example.com" }
    - "another.recipient@example.com"