铁路/邮件ora

用于Laravel电子邮件功能的包装器，增加了HTTP API和前端开发友好的视图创建和使用。

维护者

详细信息

github.com/railroadmedia/mailora

主页

源代码

问题

安装次数: 75,152

依赖者: 1

建议者: 0

安全: 0

星标: 0

关注者: 2

分支: 0

开放问题: 0

v4.0.1 2024-08-13 21:36 UTC

Requires

Requires (Dev)

MIT d6600f4d147f600542d84a7dbb0979aa79e50575

mailapiemailwrapperlaravel

This package is auto-updated.

Last update: 2024-09-13 21:53:34 UTC

README

用于Laravel电子邮件功能的包装器，增加了HTTP API和前端开发友好的视图创建和使用。

目录

1 - 安装和配置

1.1 - 安装

使用Composer运行以下命令进行安装

$ composer require railroad/mailora

或将其添加到 composer.json

{
    "require": {
        "railroad/mailora": "dev-master"
    }
}

然后运行 composer update railroad/mailora。

（我不确定关于指定要使用哪个版本的问题。也许只需使用 "dev-master"）

将 \Railroad\Mailora\Providers\MailoraServiceProvider::class, 添加到应用程序的 config/app.php 中的 providers 数组。

运行 php artisan vendor:publish，从生成的选项列表中选择此包。

这将注册视图和路由，并将配置文件复制到您的应用程序中。将配置文件提交到您的应用程序。配置的详细信息如下。

（关于此项目未来开发的次要说明）我们可能不需要这样做，但看起来Laravel中服务提供器可以仅在包自己的 composer.json 文件中注册的功能似乎不起作用，因此您必须将其添加到应用程序中。

1.2 - 配置

有两个配置文件。它们都位于您的应用程序的 "config" 目录中

  1. 'mail.php'
  2. 'mailora.php'

下面两个部分中提供了每个文件的更多详细信息。

请注意，两个配置文件都可以使用 Laravel的 "env()" 辅助函数。因此，您可以通过提供环境变量来覆盖配置文件中硬编码的任何值。这对于本地或测试环境的不同配置非常有用。

然后您可以使用 Laravel的配置辅助函数 调用这些配置值。

示例

// retrieve a value directly using dot notation
$senderAddress = config('mail.defaults.sender-address');

// or retrieve an array and access items as needed.
$mail = config('mail.defaults');
$senderName = $mail['sender-name'];

1.2.1 - Laravel本地的 'config/mail.php'

这是一个提供电子邮件发送服务详细信息的Laravel原生文件。此文件配置标准Laravel功能，您可以参考他们的文档以获取详细信息。

将您选择的电子邮件服务的密钥作为环境变量提供，不要将实际值提交到配置文件中。

您可以在配置文件中硬编码其他非敏感值。

1.2.2 - 包提供的 'config/mailora.php'

1.2.2.1 - TL;DR

提供给 config/mailora.php 的最基本内容如下

  • 安全接收者
  • 默认值
    • 发送者地址
    • 接收者地址
  • 以下两者之一或两者都
    • 认证中间件
    • 以下两者之一或两者都
      • 批准接收者
      • 批准接收者域名
1.2.2.2 - 详细信息

通过运行 artisan vendor:publish 命令，此文件将从此包复制到您的应用的 "config" 目录。

有两个基本功能。一个是通过调用未受保护的路由来发送。这向全世界开放，因此只会发送到配置中明确允许的电子邮件地址（或域名）。另一个（"安全"）仅对认证用户开放。对于前者，您必须提供 'approved-recipients' 或 'approved-recipient-domains' 值，并使用公共路由。对于后者，您必须提供一个认证中间件以使用 "安全" 路由。

1.2.2.2.1 - 顶级值
1.2.2.2.2 - "defaults" 下嵌套的值

* 注意事项——见备注

链接到配置文件模板.

1.2.3 - 认证中间件

作为 "auth_middleware" 提供一个字符串值。使用您的应用的 App\Http\Kernel 类中 "$routeMiddleware" 属性的键（根据 Laravel 功能配置配置）。

例如，如果您的 app/Http/Kernel.php 有

    protected $routeMiddleware = [
        'auth' => \WordpressAuthMiddleware::class,
        'auth-special' => \WordpressSpecialAuthMiddleware::class,
        'requires.edge' => \App\Http\Middleware\RequiresEdge::class,
        'requires.edge-or-pack' => \App\Http\Middleware\RequiresPackOrEdge::class,
        'auth.admin' => \WordpressAdminAuthMiddleware::class,
        'auth.executives' => \StatisticsWhiteListFilter::class,
        'auth.shippers' => \App\Http\Middleware\ShippersOrAdmin::class,
    ];

...那么在 config/mailora.php 中可以有以下内容

return [
    // ...
    'auth_middleware' => ['is-logged-in-or-something'],
    // ...
];

1.3 - 本地开发配置

由于 Laravel 的 env() 函数被使用，而不是在配置文件中进行更改，您可以只提供环境变量来覆盖配置文件中硬编码的任何内容。在您的应用根目录中定义一个 ".env" 文件。

至少，您应提供 "MAILORA_SAFETY_RECIPIENT"，以确保您知道电子邮件发送的位置。当环境不是 "生产"（或 config('mailora.name-of-production-env') 返回的值，如果不同的话）时，电子邮件将只发送到该地址；

示例

MAILORA_SAFETY_RECIPIENT=jonathan+mailora_dev_SAFETY_RECIPIENT@drumeo.com

或提供多个值

MAILORA_SAFETY_RECIPIENT=joe+foo@foo.com
MAILORA_APPROVED_FROM_PUBLIC_RECIPIENTS=['joe+test89347832@foo.com']
MAILORA_NAME_OF_PROD_ENV='staging'
MAILORA_PUBLIC_FREE_FOR_ALL=true
MAILORA_DEFAULT_ADMIN=joe+bar@foo.com
MAIL_FROM_ADDRESS=joe+baz@foo.com
MAIL_FROM_NAME="Joe Black"
MAILORA_DEFAULT_RECIPIENT=joe+qux@foo.com
MAILORA_DEFAULT_TYPE='foo'

2 - 特性

2.1 - 通过POST请求发送电子邮件到端点

要发送电子邮件，只需按这些文档中描述的方式发送 POST 请求。您将收到一个简单的 "sent" 布尔值响应。

2.2 - 配置常用操作的默认值

始终发送到同一电子邮件地址。在配置中将其设置为默认值，然后在请求发送到该地址时，不要传递 "recipient-address" 值。将使用默认值。

事实上，端点没有必需的参数——您可以将所有必需的信息放入配置中，并在需要时只提供唯一信息。

2.3 - "一站式视图变量"

您可以轻松传递所需值，并在自定义视图中使用它们。无需 PHP。

2.3.1 - 访问传递给视图的值

在请求中传递给视图的值嵌套在 $input 变量中。

因此，如果您传递

$.ajax({
    url: 'https://www.foo.com/mailora/secure/send' ,
    type: 'get',
    dataType: 'json',
    data: {
    'type': 'layouts/action',
    'lines': [
        'foo_lines_bar_line_1',
        'foo_lines_bar_line_2',
        'foo_lines_bar_line_3',
        'foo_lines_bar_line_4',
        'foo_lines_bar_line_5',
        'foo_lines_bar_line_6'
    ],
    'callToAction': {
        'url': 'foo_callToAction_bar',
        'text': 'foo_callToAction_bar',
    },
    'logo': 'foo_logo_bar',
    'brand': 'foo_brand_bar',
    'subject': 'important action!!'
    },
    success: function(response) { /* handle error */ },
    error: function(response) { /* handle error */ }
});

您可以通过在视图中使用 $input 变量来访问您传递的自定义值。例如

<table>
    @foreach($input['lines'] as $line)
        <tr><td>{{ $line }}</td></tr>
    @endforeach
    @if(!empty($input['callToAction']))
        <tr><td><a href="{{ $input['callToAction']['url'] }}">{{ $input['callToAction']['text'] }}</a></td></tr>
    @endif
    <tr><td>— The {{ $input['brand'] ?? 'Musora' }} Team</td></tr>
</table>

注意 $line 变量。这是在 foreach 循环中定义的，因此它不是 $input[line]。

2.2 - 简易自定义视图

如果在请求中未提供 'type' 值，将使用 Mailora 的通用类和 general.blade.php 视图。如果传递了类型值，Mailora 将寻找与传递的 CapitalizedCamelCase 版本匹配的类。Mailora 将在由 config('mailora.mailables-namespace') 返回的命名空间中寻找此类。如果存在此类，则使用它。如果没有使用任何类，Mailora 的 General 类将被使用。此类仅使用提供的任何视图，并将 $input 参数传递给视图，以便从其中检索所有值。

这使以下内容成为可能。

无论使用什么类——也就是说，即使没有找到与转换后的 CapitalizedCamelCase 'type' 值匹配的 Mailable 类，Mailora 也将在由 config('mailora.views-directory') 返回的目录中寻找与该类型值匹配的视图文件**。如果找到，则使用它。如果没有找到，则使用 mailora 的 general.php***。

所有这些的综合结果是，无需后端修改即可创建新的电子邮件模板。 只需创建一个视图文件，并从 $input 参数中提供和检索值。

TL;DR 关于请求数据中指定的 'type' 值。如果可能，它将解析为类。否则，将使用默认的 General PHP Mailable 类，并且 'type' 将解析为视图，如果可能。否则，将使用默认的 'general.blade.php'。

* 值 foo-bar-baz 将使用类 FooBarBaz 和视图文件 "foo-bar-baz.blade.php"。

** 这可以在 mailora.php 配置文件中设置——因此可以更改

*** 注意此文件位于 "/your-application/vendor/railroad/mailora/resources/views/"

2.2.1 - 类和视图使用的流程图

is type defined in request? → no → use 'general' view and 'General' Mailable class
↓
yes
↓
is type defined in request as 'general'? → yes → use 'general' view and 'General' Mailable class
↓
no
↓
is there a Mailable class that matches a CapitalizedCamelCase version of the 'type' value supplied? → yes → use that
↓
no
↓
use 'General'
↓
is there a view file matching the 'type' value passed? → no → use mailora's general.blade.php
↓
yes
↓
use that

2.2.2 - 视图文件嵌套在邮件目录的子目录中

要指定子目录（电子邮件目录的子目录）中的视图，只需键入视图文件的相对路径。

例如，假设您的视图目录是： /appFoo/resources/views/emails。您可以通过将电子邮件请求的 "type" 值指定为 "fooView" 来使用视图文件 /appFoo/resources/views/emails/fooView.blade.php。但如果你在 emails/barDir 目录中有视图文件怎么办？比如可能是这样的 /appFoo/resources/views/emails/barDir/quxView.blade？那么，您只需指定类型为 barDir/quxView。

当然，所有这些都是假设您不需要任何通过自定义 Laravel Mailable PHP 类实现的获取或特殊转换，并且您可以使用默认的 Mailora General PHP 类。

3 - API参考

有两个端点

  1. POST /mailora/public/send（公开访问）
  2. POST /mailora/secure/send（用户必须经过身份验证才能访问此端点）

以下为详细信息。

除了以下列出的参数外，还可以传递任何其他参数，并且它将在视图中可用！

例如，如果您在请求的数据中有 'foo' : 'bar' 项，在视图中，{{ $input['foo'] }} 将打印 "bar"。

另一个示例：请求中的 'foo' : 1 允许视图中使用 {{ $input['foo'] ? 'true' : 'false' }}。

3.1 - 从任何地方发送电子邮件

POST /mailora/public/send/

可以从任何地方调用。适用于从公开访问的支持和销售页面发送电子邮件。

不能指定收件人。除非提供了 MAIL_FROM_ADDRESS_PUBLIC，否则将发送到 MAIL_FROM_ADDRESS。尽管如此，您可以设置 "发件人姓名"。

用户必须在配置文件 "config/mailora.php" 中定义。如果用户不在那里，则不会将电子邮件发送到指定的收件人。

3.1.1 - 请求示例

let data = {
    "type": "foo",
    "sender-address": "bar@some-domain.com",
    "sender-name": "Baz Qux",
    "recipient": [
        "foo+test_0@bar.com",
        "foo+test_1@bar.com",
        {
           "name":"foo_test_2",
           "address":"foo+test_2@bar.com"
        },
        {
           "name":"foo_test_3",
           "address":"foo+test_3@bar.com"
        },
        {
           "name":"foo_test_4",
           "address":"foo+test_4@bar.com"
        }
     ],
    "subject": "Grault garply waldo",
    "reply-to": "bar@some-domain.com",
    "users-email-set-reply-to": "",
    "message": "Fred plugh thud, mos henk. Def."
};

$.ajax({
    url: 'https://www.foo.com/mailora/secure/send' ,
    type: 'get',
    dataType: 'json',
    data: data,
    success: function(response) { /* handle error */ },
    error: function(response) { /* handle error */ }
});

或者，如果您只有一个指定项，而不是 "recipient"，请设置 "recipient-address"（可选地，设置 "recipient-name"）。

let data = {
    "type": "foo",
    "sender-address": "bar@some-domain.com",
    "sender-name": "Baz Qux",
    "recipient-address": "foo+test_0@bar.com",
    "subject": "Grault garply waldo",
    "reply-to": "bar@some-domain.com",
    "users-email-set-reply-to": "",
    "message": "Fred plugh thud, mos henk. Def."
};

3.1.2 - 请求参数

请将所有参数放在请求体中。

注意，没有字段是 必需的！！

注意 1：除非同时提供来自同一来源的地址，否则不会使用提供的名称。例如：假设发送者地址和发送者名称都在配置文件中设置。如果请求没有指定请求地址，则将使用配置中的地址和名称。但是，如果请求提供地址但没有名称，则将使用请求中的地址（而不是配置中的名称）。配置中的名称仅在配置中的地址使用时才使用。当在请求中提供地址时，只有请求中类似提供的名称才会使用。来自配置的名称不会使用，如果请求中提供了电子邮件地址。

注意 2：将任何数量的收件人作为数组中的项目传递，格式为 JSON 字符串。数组中的每个收件人都是一个项目。有两种方式指定数组中的每个收件人

  1. 作为地址的字符串。
  2. 作为定义了 "address" 的对象字面量，并可选地定义了 "name"

示例

[
   "foo+test_0@bar.com",
   "foo+test_1@bar.com",
   {
      "name":"foo_test_2",
      "address":"foo+test_2@bar.com"
   },
   {
      "name":"foo_test_3",
      "address":"foo+test_3@bar.com"
   },
   {
      "name":"foo_test_4",
      "address":"foo+test_4@bar.com"
   }
]

此外，将来将重命名为 "recipients"。

3.1.3 - 响应示例

3.1.3.1 - {200 OK}
{"sent":true}
3.1.3.2 - {500 Internal Server Error}
{"sent":false}

或者

{"error":true}

fin

glhf