README

这是一个预先配置的 REMP 邮件应用程序框架，具有简单的安装过程。

邮件框架作为配置邮件工具、创建电子邮件布局和模板以及向选定的用户段配置和发送邮件作业的工具。

安装

Docker

最简单的方法是在 Docker 容器中运行此应用程序。使用 Docker Compose 进行编排。除了这两个应用程序之外，主机机器上不需要安装任何东西。

在 Docker 中安装应用程序的步骤

获取应用程序

A) 使用 Composer

composer create-project --no-install remp/mailer-skeleton path/to/install

cd path/to/install

B) 使用 GitHub

git clone https://github.com/remp2020/mailer-skeleton.git

cd mailer-skeleton

准备环境和配置文件
```
cp .env.example .env
```
```
cp app/config/config.local.neon.example app/config/config.local.neon
```
```
cp docker-compose.override.example.yml docker-compose.override.yml
```
如果您想直接运行应用程序，不需要进行任何更改。

注意： nginx 网络应用程序运行在端口 80 上。请确保此端口未被使用，否则在初始化 Docker 时您将遇到如下错误
```
ERROR: for nginx  Cannot start service nginx: Ports are not available: listen tcp 0.0.0.0:80: bind: address already in use
```
在这种情况下，请更改 docker-composer.override.yml 中的端口映射。例如，以下设置将内部端口 80 映射到外部端口 8080，因此应用程序将在 http://mailer.press:8080 上可用。
```
services:
# ...
  nginx:
    ports:
      - "8080:80"
```
设置主机

应用程序默认使用的主机是 http://mailer.press。此域名应指向本地主机（127.0.0.1），因此请将其添加到本地 /etc/hosts 文件中。此外，我们建议添加 mailhog.mailer.press 域名进行测试。使用以下命令
```
echo '127.0.0.1 mailer.press' | sudo tee -a /etc/hosts
```
```
echo '127.0.0.1 mailhog.mailer.press' | sudo tee -a /etc/hosts
```
启动 Docker 容器
```
docker compose up
```
您应看到容器的启动日志。这可能包括错误，因为应用程序尚未初始化。进入应用程序 Docker 容器
```
# run from anywhere in the project
docker compose exec mailer bash
```
在容器内部，添加所需的权限
```
chmod -R a+rw temp log
```
之后，选择并运行以下两种安装选项之一
- 包含演示数据的完整应用程序
```
make install-demo
```
- 无演示数据
```
make install
```
登录到 Mailer

通过网页浏览器访问应用程序。默认配置
- URL: http://mailer.press/
- 用户
  - 电子邮件: admin@admin.sk
  - 密码: passphrase_change_me
重要： 请每次使用 composer update 更新 Mailer-skeleton 时都运行 make install。

手动安装

依赖

PHP 8.1
MySQL 8
Redis 6.2

安装

克隆此存储库，进入文件夹并运行以下命令以从示例文件创建配置文件

cp .env.example .env

cp app/config/config.local.neon.example app/config/config.local.neon

编辑 .env 文件并设置所有必需的值，例如数据库和 Redis 连接。

现在运行安装程序

make install

作为替代方案，运行以下命令以在安装中包含演示值的播种

make install-demo

邮件框架概述

默认集成

在安装邮件框架骨架后，邮件框架使用默认（本地）集成，在上线之前需要用真实实现替换这些集成。本地集成作为参考和默认设置，允许在不进行额外工作的前提下发送测试电子邮件。

身份验证

SimpleAuthenticator 负责工具的身份验证。

凭据列表配置在 config.local.neon 文件中。默认凭据是

电子邮件: admin@admin.sk
密码: passphrase_change_me

请不要使用默认凭据通过 SimpleAuthenticator 在公共环境中运行 Mailer。

邮件集成

发件邮件由 SmtpMailer 发送。要配置不同的邮件发送器（例如 MailGun），请查阅文档中的邮件发送器部分。SMTP 邮件发送器的配置从 config.local.neon 加载，请参阅 local_configs 部分（该部分覆盖数据库中存储的任何配置选项）

local_configs:
    default_mailer: remp_smtp
    remp_smtp_host: mailhog
    remp_smtp_port: 1025

键 remp_smtp_host 指向 mailhog。这是 mailhog docker 容器的内部 docker 地址。该容器运行 MailHog，这是一个基于网页的 SMTP 测试工具。因此，从 Demo Mailer 实例发送的所有邮件都被 MailHog 捕获，并且可以在 http://mailhog.mailer.press 的 MailHog 网页界面中轻松查看。

用户基础集成

邮件发送器依赖于外部权限以获取有关用户的信息。默认情况下，使用 Dummy 用户提供者实现作为用户信息的默认来源。提供者列出了 2 个演示用户（foo@example.com，bar@example.com）。有关如何实现不同的用户提供者的信息，请参阅文档。

分段集成

要发送时事通讯，邮件发送器需要获取应接收它的用户分组。为了补充默认的用户基础集成，还有一个 Dummy 分段提供者实现，始终返回包含两个演示用户的相同分组。

调试模式

安装后，邮件发送器以调试模式运行，并显示所有调试信息。请勿在生产环境中运行此模式。 要禁用此模式，请更改 .env 配置文件中 ENV 键的值

# previously was `local` (debug ON)
ENV=production

基本场景 - 向用户分组发送电子邮件

为了测试邮件发送器的功能，我们建议您按照以下基本场景进行操作

登录到 URL http://mailer.press 的邮件发送器
转到作业
点击 添加新作业
在 包含分段、时事通讯列表 和 电子邮件 A 替代 输入中选择值。保留其他输入为空。
- 默认情况下，在演示安装中已预置 电子邮件、布局和 时事通讯列表 的演示值。
点击 保存并启动 按钮
等待大约一分钟，以便邮件发送器处理作业。在作业页面上检查作业状态。
作业处理完毕（状态为 "完成"）后，转到 http://mailhog.mailer.press/ 并检查是否成功接收了电子邮件。

定制

Mailer-skeleton 已准备好进行定制。有关更多信息，请参阅 mailer-module 文档。

作为示例，mailer-skeleton 提供了 app/Commands/SampleCommand.php，它扩展了 Command 类。它在 config.local.neon 文件中注册为新的命令。通过连接到容器并执行以下命令来运行它

docker compose exec mailer bash

php bin/command.php mail:sample-command

故障排除

一些已知错误及其修复方法。

Docker SMTP 错误 "无法分配请求的地址"

在某些情况下（例如首次运行容器时），Docker 容器可能会报告此错误消息。只需重新启动有问题的容器即可解决问题。

remp / mailer-skeleton

维护者

详细信息