README

使用单个 Laravel artisan 命令设置 AWS 基础设施以处理电子邮件事件，并通过 SES/SNS 和 http/s 端点接收电子邮件事件通知。此包在设置方面没有限制，每个设置都可以根据您的需求进行更改。它遵循基于交互式 CLI 的设置过程，以便您确切了解将要配置的内容。此外，还包括调试模式，您可以查看将要使用的所有设置和配置，而无需实际进行 API 调用。最后，当 API 调用失败时，清理 AWS 资源可能会非常痛苦。例如，如果您尝试为端点启用某些高级过滤器策略，而该设置失败，那么您可能需要手动删除配置集和 SNS 主题。为了解决此问题，该包将在发生任何异常时自动尝试撤销对 AWS 基础设施所做的任何更改。

此包的作用

如前所述，此包自动化以下过程：

• 设置 SES 配置集。
• 设置 SNS 主题。
• 设置配置集的事件目的地。
• 将 http/s 端点订阅到 SNS 主题。

此包不做什么

此包将不会执行上述之外的操作。因此，该包不会

• 将创建的配置集添加到您的 SES 驱动器中。
• 管理 https/s 订阅确认或实际处理来自 SNS 的事件消息。
• 在运行 Laravel 项目的域中创建域或端点（但这难道不酷吗 😃）。

如果您正在寻找一个可以管理传入 SES 通知并跟踪电子邮件事件的包，则可以查看 Laravel Ses Event Manager 包。Laravel Ses Event Manager 包与此包很好地集成，并处理发送到 webhooks 的电子邮件事件通知的处理和存储。

完全披露：我是 Laravel Ses Event Manager 包的作者。

Laravel 和 PHP 版本

此包是为 Laravel 9 和 Php 8 及更高版本编写的。

SES/SNS 事件通知过程概述

要了解在 AWS 上设置电子邮件事件通知的过程，我们必须知道需要在这些服务上设置的 2 个关键对象

• 配置集（《SES》）
• 主题（《SNS》）

为了在我们的 http/s 端点上接收电子邮件通知，我们首先需要在 SES 上设置一个 Configuration Set。配置集与 Laravel 中的 ses 驱动器一起使用。这告诉 AWS 我们希望向某个监听器发送电子邮件事件通知。

在我们的情况下，“某个监听器”将是 SNS 主题。这是通过创建 Event Destinations 来指定的。事件目的地有两个用途：

• 指定要发送通知的事件。
• 指定将事件通知发送到何处。

由于我们想使用 SNS 主题，因此我们接下来需要创建一个 SNS 主题。SNS 主题接收 SES 的事件通知。当 SNS 收到通知时，它将向在主题上监听的所有 订阅者 发送消息。在这种情况下，订阅者将是 http/s 端点。

因此我们需要创建4个对象

• 配置集
  • 事件目标（配置集的一部分）
• 主题
  • 订阅（订阅主题）

这是启用http/s端点接收电子邮件事件通知所需设置的一个简要概述。

安装

通过Composer

$ composer require akhan619/laravel-ses-tracking

该包使用Laravel的包自动发现，因此无需在config/app.php中添加服务提供者

配置文件

您可以使用以下artisan命令发布配置文件

$ php artisan vendor:publish --provider="Akhan619\LaravelSesTracking\LaravelSesTrackingServiceProvider" --tag="config"

这将会在config文件夹中发布一个名为laravel-ses-tracking.php的新配置文件。

用法

调试模式

默认情况下，该包配置为在调试模式下运行。这意味着当您运行设置命令时，该包将显示所有将要用于实际API调用的配置选项，包括路由/主题/订阅等。您可以通过在config中设置debug => FALSE来关闭调试模式。

在调试模式下不会发出API调用。因此，您可以在不更改您的AWS资源的情况下测试不同的配置可能性。

设置

运行以下命令并遵循交互步骤。

$ php artisan SesTracking:setup

您需要确认

• 用作端点的路由名称。
• SNS的主题名称。
• SES的事件目标名称。

一旦您确认这3个，该包将创建并订阅端点到SNS主题。

在成功时，SubscriptionArns将打印到控制台。除非您在配置中启用ReturnSubscriptionArn，否则它们将显示为待确认。

示例运行

确认订阅

您需要自己设置实际端点服务的代码以确认订阅。目前，您有72小时的时间在订阅过期之前确认订阅。您可以从AWS控制台重新发送确认消息。

配置

AWS凭证

AWS凭证从.env文件中获取

AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=
AWS_DEFAULT_REGION=

如果您希望使用不同的凭证集，则可以在配置文件中的ses键下指定它们。

'ses' => [
    'key' => env('AWS_ACCESS_KEY_ID'),
    'secret' => env('AWS_SECRET_ACCESS_KEY'),
    'region' => env('AWS_DEFAULT_REGION'),
],

注意：AWS凭证必须具有允许以下权限：

• 创建SES配置集
• 创建SNS主题
• 创建SES事件目标
• 将http/s端点订阅到SNS主题

由于这是一个本身也是主题的内容，请参阅AWS文档以了解需要设置哪些权限。

SNS协议

目前支持2种SNS协议：http/https。默认为https。您可以通过在subscriber键下设置其中一个为true来更改协议。

'subscriber' => [
    'http' => FALSE, 
    'https' => TRUE,
],

域名和方案

默认情况下，该包从.env文件中的APP_URL获取用于端点的domain和scheme。如果您希望使用与项目URL不同的端点，请指定配置文件中相应键下的值。

'domain' => null, // If null the domain will be pulled from APP_URL. 

'scheme' => null, // If null the scheme will be pulled from APP_URL. 

注意：当使用http/s订阅者时，方案必须与订阅者SNS协议匹配。

事件

您可以通过在active键中将事件设置为true来指定您想要监听的确切电子邮件事件。

'active' => [
    'sends' => TRUE,
    'rendering_failures' => TRUE,
    'rejects' => FALSE,
    'deliveries' => FALSE,
    'bounces' => TRUE,
    'complaints' => FALSE,
    'delivery_delays' => FALSE,
    'subscriptions' => FALSE,
    'opens' => FALSE,
    'clicks' => FALSE,
],

路由

可以为每个事件自定义路由，通过指定route_prefix和routes键的值。

'route_prefix' => 'email/notification', // Set to null if no prefix is required.

'routes' => [
    'sends' => 'sends',
    'rendering_failures' => 'rendering-failures',
    'rejects' => 'rejects',
    'deliveries' => 'deliveries',
    'bounces' => 'bounces',
    'complaints' => 'complaints',
    'delivery_delays' => 'delivery-delays',
    'subscriptions' => 'subscriptions',
    'opens' => 'opens',
    'clicks' => 'clicks',
],

然后为每个事件单独生成实际端点，如下所示

scheme://domain/route_prefix/route

注意：只为启用的事件生成和订阅路由端点。

路由确认

运行设置命令时，该软件包会输出到控制台将要配置在AWS上的http/s端点（在实时模式下运行时，用户将要求确认路由）。这允许您确保端点正好符合您的需求。

输出如下（基于具有默认值的全新Laravel项目）

配置集

该软件包在SES中创建一个配置集，您可以使用它来获取您希望事件通知的电子邮件。所有在AWS控制台上可用的选项都可以通过配置文件设置。

'configuration_set' => [
    'ConfigurationSetName' => 'ses-event',

    'DeliveryOptions' => [
        'SendingPoolName' => null,

        'TlsPolicy' => 'REQUIRE',
    ],

    'ReputationOptions' => [
        'LastFreshStart' => null,

        'ReputationMetricsEnabled' => FALSE,
    ],

    'SendingOptions' => [
        'SendingEnabled' => TRUE,
    ],

    'SuppressionOptions' => [
        'SuppressedReasons' => [],
    ],

    'Tags' => [],

    'TrackingOptions' => [
        'CustomRedirectDomain' => null,
    ],
],

注意：此处的一些选项在启用时将由AWS单独收费。您应根据您的使用情况检查这里设置的默认值。请参阅AWS文档以了解如何设置这些选项及其影响。

SNS主题

与路由名称类似，可以通过更改配置中的topic_name_prefix、topic_name_suffix和topic_name键来修改每个事件生成的主题名称。

'topic_name_prefix' => env('APP_NAME', 'local'), // Set to null if no prefix is required.

'topic_names' => [
    'sends' => 'sends',
    'rendering_failures' => 'rendering-failures',
    'rejects' => 'rejects',
    'deliveries' => 'deliveries',
    'bounces' => 'bounces',
    'complaints' => 'complaints',
    'delivery_delays' => 'delivery-delays',
    'subscriptions' => 'subscriptions',
    'opens' => 'opens',
    'clicks' => 'clicks',
],

'topic_name_suffix' => 'us-east-1', // Set to null if no prefix is required.

SNS主题配置

在创建SNS主题时，除了名称之外，还可以设置其他选项。例如，您可能希望启用静默加密以加密负载或定义交付重试策略。这些可以在配置文件中的sns_topic_configuration_data键下指定。请参阅AWS文档以了解如何正确设置它们。

'DeliveryPolicy' => [],

'Policy' => [],

'KmsMasterKeyId' => null,

'Tags' => [],

SNS主题名称确认

运行设置命令时，该软件包将输出到控制台将在AWS上配置的SNS主题（在实时模式下运行时，用户将要求确认主题名称）。这允许您确保主题名称正好符合您的需求。

输出如下（基于具有默认值的全新Laravel项目）

事件目的地名称

就像之前一样，可以通过更改以下自解释配置选项按事件定制事件目的地名称。

'event_destination_prefix' => 'destination',

'destination_names' => [
    'sends' => 'sns',
    'rendering_failures' => 'sns',
    'rejects' => 'sns',
    'deliveries' => 'sns',
    'bounces' => 'sns',
    'complaints' => 'sns',
    'delivery_delays' => 'sns',
    'subscriptions' => 'sns',
    'opens' => 'sns',
    'clicks' => 'sns',
],

'event_destination_suffix' => 'us-east-1',

如果您想将主题名称作为事件目的地的后缀附加，以帮助跟踪，则将以下选项设置为TRUE。

'topic_name_as_suffix' => TRUE,

将此设置为TRUE将禁用event_destination_suffix。

事件目的地名称确认

运行设置命令时，该软件包将输出到控制台将在AWS上配置的SES事件目的地名称（在实时模式下运行时，用户将要求确认目的地名称）。这允许您确保目的地名称正好符合您的需求。

输出如下（基于具有默认值的全新Laravel项目）

订阅配置

您可以在配置文件中的sns_subscription_configuration_data键下指定订阅端点到SNS主题时的附加选项。目前可以设置以下选项。

'ReturnSubscriptionArn' => false,

'DeliveryPolicy' => [],

'FilterPolicy ' => [],

'RawMessageDelivery' => 'false',

'RedrivePolicy' => null,

请参阅AWS文档以获取有关如何使用这些设置的更多详细信息。

失败回滚

API调用总是存在失败的可能性。因此，在调用之前，每个配置设置都经过广泛的验证。尽管如此，API调用可能会失败。也许，主题名称已经存在。由于这是一个多步骤的过程，您可能会留下浪费的资源，您需要亲自清理。因此，该软件包尝试回滚到干净状态。这意味着在后续步骤失败的情况下，它将删除配置集和/或创建的主题。这应该对大多数情况足够了。但是，删除这些资源的调用可能会失败。在这种情况下，需要遗憾的是进行手动清理。

如果您处于这种情况，那么作为一个安慰，这个开发者在这个软件包开发过程中不得不多次手动清理。

变更日志

请参阅变更日志以获取有关最近更改的更多信息。

测试

使用以下命令运行测试

$ composer test

路线图

• 添加测试！！！
• 添加一个命令行选项，以回答所有确认问题的“是”。
• 添加一个独立的命令来删除创建的AWS资源。这是用户测试和清除AWS资源的一种方式。
• 添加其他协议，如SQS。

贡献

有关详细信息和使用待办事项，请参阅contributing.md。

安全

如果您发现任何与安全相关的问题，请通过电子邮件amankhan.mailbox@gmail.com联系，而不是使用问题跟踪器。

鸣谢

• Aman Khan

许可协议

MIT。有关更多信息，请参阅许可文件。