README

此库将 Postal 与标准的 Laravel 邮件框架集成。

安装

首先，使用 Composer 安装此包

composer require synergitech/laravel-postal

然后，运行包迁移

php artisan migrate

然后，将凭证添加到您的 .env 文件中，并将邮件驱动设置为 postal

MAIL_MAILER=postal

POSTAL_DOMAIN=https://your.postal.server
POSTAL_KEY=yourapicredential

最后，将 postal 添加到您的 config/mail.php 文件中的邮件发送器

'mailers' => [
    'postal' => [
        'transport' => 'postal',
    ],
],

如果您想进一步修改配置，可以参考 config/postal.php 文件以了解应放在环境中的键。或者，如果您想进行特定更改，可以像往常一样发布配置文件

php artisan vendor:publish --provider="SynergiTech\Postal\PostalServiceProvider"

同时确保您已经填写了电子邮件发送者信息，并且您使用的域名已通过 API 凭证授权。

MAIL_FROM_ADDRESS=noreply@your.company
MAIL_FROM_NAME="Your Company"

用法

由于这是一个主 Laravel 邮件框架的驱动程序，发送电子邮件与平常一样 - 只需遵循 Laravel 邮件文档 - 但是我们建议您使用 PostalNotificationChannel 类来在您的软件中启用完整的电子邮件跟踪。

升级

升级到 V4

由于 Laravel 处理电子邮件的重大变化，版本 4 只支持 Laravel 9 及更高版本。

现在，当发生 API 错误时，我们抛出 TransportException，而不是 BadMethodCallException。

升级到 V3

如果您同时更新到 Laravel 7，您需要更新您的环境变量名称。

从 V1 升级到 V2

请注意版本 2 与版本 1 兼容，前提是你没有使用监听器。版本 2 的配置也不同，并且包含许多更多功能（包括对 Webhooks 的支持），所以如果您从版本 1 升级，请花时间重新阅读此信息。

从 V2 升级到 V2.1

这两个版本之间没有向后不兼容的更改，除非您已自定义默认表名。在 v2.1 之前，我们将迁移文件发布到您的应用程序中。从 v2.1 开始，我们现在将这些文件呈现给 Laravel 在我们的服务提供者中。

在升级到这两个版本之间时，我们的迁移将再次运行。当检测到默认表存在时，迁移不会重新创建表或产生错误。但是，如果它们已被重命名，则将重新创建。只需创建一个新的迁移来删除表。

记录针对可通知模型发送的消息

创建一个 email 通知，就像您通常所做的那样，但在 via() 方法中返回 'SynergiTech\Postal\PostalNotificationChannel' 或 PostalNotificationChannel::class。

为了将消息与可通知模型关联起来，您需要在您的通知类中返回模型对象的方法 logEmailAgainstModel。如果您不包含此方法，则消息仍会记录（如果您已在配置中启用此功能），但不会创建与您的可通知模型的联系。

以下是确保您的可通知模型与发送的电子邮件相关联所需完成的完整示例。

use App\Notifications\EnquiryNotification;
use Illuminate\Support\Facades\Notification;
use SynergiTech\Postal\PostalNotificationChannel;

// Using the Notifiable trait
$user->notify(new EnquiryNotification($enquiry));

// On demand notifications
Notification::route(PostalNotificationChannel::class, 'john.smith@example.com')
    ->notify(new EnquiryNotification($enquiry));

namespace App\Notifications;

use Illuminate\Notifications\Notification;
use SynergiTech\Postal\PostalNotificationChannel;

class EnquiryNotification extends Notification
{
    private $enquiry;

    public function __construct($enquiry)
    {
        $this->enquiry = $enquiry;
    }

    public function via($notifiable)
    {
        return [PostalNotificationChannel::class];
    }

    public function logEmailAgainstModel()
    {
        return $this->enquiry;
    }

    public function toMail($notifiable)
    {
        // message constructed here
    }
}

您仍然可以作为驾驶员通过邮政发送消息，只需在 via() 方法中保留 'mail' 即可，但此包中的通道负责创建链接，因此如果您没有像上面提到的那样使用 PostalNotificationChannel，消息和您的可通知模型之间将不会建立链接。

请注意，如果 Postal 的 PHP 客户端在尝试将消息提交到服务器失败时（例如，发生权限问题或电子邮件地址无效），则可能会抛出异常，因此如果您有一个依赖于发送电子邮件的过程，那么在继续之前（例如，将更新后的对象保存到数据库）发送通知将是一个好主意。

将所有电子邮件发送到同一地址（例如，用于开发）

我们为 FuelPHP 提供的类似包允许您将所有消息发送到在您的环境中定义的特定电子邮件地址。Laravel 已经有了一个这样的机制，您可以通过更新 config/mail.php 文件来使用它，如下所示

$config = [
    // existing config array
];

if (getenv('EMAIL')) {
    $config['to'] = [
        'address' => getenv('EMAIL'),
        'name' => 'Your Name'
    ];
}

return $config;

Webhooks

此包还提供了您从 Postal 记录 webhooks 的能力。此功能默认启用。

验证 webhook 签名

每个 webhook 有效负载都应该包含一些独特的值，以便在您的 webhooks 中有一定的准确性，但如果您想验证签名，则必须提供 Postal 的签名密钥并启用此功能。

您可以通过在 Postal 服务器上运行 postal default-dkim-record 来访问签名公钥，并将 p 参数的值（不包括分号）复制到您的环境中的 POSTAL_WEBHOOK_PUBLIC_KEY 键下。

监听器

与默认的 Laravel 一样，您可以使用 Illuminate\Mail\Events\MessageSent 监听器。在版本 1 中，您接收了 Postal 的整个响应，但在版本 2 中，您将只收到一个 Postal-Message-ID，并且它包含在消息头中。这将允许您访问创建的电子邮件，因为这将作为 postal_email_id 列的值。

此更改允许您的代码满足静态分析要求。

namespace App\Listeners;

use Illuminate\Mail\Events\MessageSent;

class MessageSentListener
{
    /**
     * Handle the event.
     *
     * @param MessageSent $event
     * @return void
     */
    public function handle(MessageSent $event)
    {
        $headers = $event->message->getHeaders();
        $postalmessageid = $headers->get('postal-message-id')?->getBodyAsString();

        if ($postalmessageid) {
            // do something here
        }
    }
}

运行测试

要运行完整的单元测试套件

vendor/bin/phpunit -c phpunit.xml

您需要安装 xdebug 以生成代码覆盖率。

Docker

提供了一个示例 Dockerfile，用于设置一个环境来运行测试，而无需配置您的本地机器。Dockerfile 可以通过参数测试 PHP 和 Laravel 的多个版本组合。

docker build . --build-arg PHP_VERSION=8.1 --build-arg LARAVEL=9

synergitech / laravel-postal

维护者

详细信息