README

一个最小的PHP Postmark SDK，允许您通过PostmarkApp.com服务发送单个和批量电子邮件。

设计
安装
创建邮件
发送邮件
开发
- 运行测试
- 虚拟机

设计

为了保持可靠性，某些对象用于数据（如电子邮件和元数据），以确保数据符合规范或开发者能尽快了解。

安装

$ composer require shawnmccool/minimal-php-postmark-sdk

创建邮件

Mailing类表示一个将发送给单个收件人的单个实例。

简单邮件

收件人、发件人、主题和正文。

<?php

use MinimalPhpPostmarkSdk\{Mailing, Email};

new Mailing(
    'from name',
    Email::fromString('from@email.com'),
    Email::fromString('to@email.com'),
    'subject line',
    'email body'
);

标签和元数据

配置消息标签和元数据，以将邮件与实体、事件等关联。

<?php

use MinimalPhpPostmarkSdk\{Mailing, Email};

new Mailing(
    'from name',
    Email::fromString('from@email.com'),
    Email::fromString('to@email.com'),
    'subject line',
    'email body',
    [],
    'holiday-sales-campaign',
    [
        'user_id' => 1,
        'description' => 'this information may be maximum 80 characters'
    ]
);

文件附件

可以附加多个文件。

<?php

use MinimalPhpPostmarkSdk\{Mailing, Email, Attachment};

new Mailing(
    'from name',
    Email::fromString('from@email.com'),
    Email::fromString('to@email.com'),
    'subject line',
    'email body',
    [
        new Attachment(
            'filename.pdf',
            'application/pdf',
            file_get_contents('local.pdf')
        )
    ]
);

Postmark模板

您可以使用Postmark模板功能而不是指定主题行和HTML正文。在Postmark用户界面中构建模板，并在邮件中指定其ID或别名。

<?php

use MinimalPhpPostmarkSdk\{Mailing, Email};

new Mailing(
    'from name',
    Email::fromString('from@email.com'),
    Email::fromString('to@email.com'),
    null, null, [], '', [],
    'postmark template alias'
);

或者

<?php

use MinimalPhpPostmarkSdk\{Mailing, Email};

new Mailing(
    'from name',
    Email::fromString('from@email.com'),
    Email::fromString('to@email.com'),
    null, null, [], '', [], '',
    'template id'
);

Postmark模板允许变量。创建一个模板模型来填充这些变量。

<?php

use MinimalPhpPostmarkSdk\{Mailing, Email};

new Mailing(
    'from name',
    Email::fromString('from@email.com'),
    Email::fromString('to@email.com'),
    null, null, [], '', [], '',
    'template id',
    [
        'customer_name' => 'Roger',
        'product_name' => 'A really fun gift.'
    ]
);

命名参数

创建邮件时有很多选项。可以创建一个更丰富和复杂的对象模型来减少可选构造函数参数的需求。但为了简单性和类功能完整，我们将保持现状。

如果您不喜欢空参数，可以创建一个包装类，或者您可能更喜欢使用命名参数。

<?php

use MinimalPhpPostmarkSdk\{Mailing, Email};

new Mailing(
    fromName: 'from name',
    fromEmail: Email::fromString('from@email.com'),
    toEmail: Email::fromString('to@email.com'),
    templateId: 'template id',
    templateModel: [
        'customer_name' => 'Roger',
        'product_name' => 'A really fun gift.'
    ]
);

发送邮件

Postmark API

您需要一个来自Postmark的服务器令牌。

PostmarkApi类处理与Postmark API的交互。

<?php

use MinimalPhpPostmarkSdk\PostmarkApi;

$postmark = new PostmarkApi('server token');

单个邮件

发送单个邮件与发送批量邮件不同。响应是SuccessResponse或ErrorResponse实例。

use MinimalPhpPostmarkSdk\{ErrorResponse,PostmarkApi,Mailing,Email,SuccessResponse};

$mailing = new Mailing(
    'from name',
    Email::fromString('from@email.com'),
    Email::fromString('to@email.com'),
    null, null, [], '', [], '',
    'template id'
);

$response = (new PostmarkApi('server token'))->single($mailing);

echo match (get_class($response)) {
    SuccessResponse::class => "Successfully sent message {$response->messageId()}.",
    ErrorResponse::class => "Could not send message. {$response->errorMessage()}",
};

批量邮件

批量邮件是一个邮件数组，将被分批发送到Postmark API。这可以防止为每个邮件建立新的API连接。默认情况下，批量邮件将一次性发送500封邮件；但这可以配置。

use MinimalPhpPostmarkSdk\{PostmarkApi,Mailing,Email};

$mailings = [
    new Mailing(
        'from name',
        Email::fromString('from@email.com'),
        Email::fromString('to@email.com'),
        null, null, [], '', [], '',
        'template id'
    ),
    new Mailing(
        'from name',
        Email::fromString('from@email.com'),
        Email::fromString('to@email.com'),
        null, null, [], '', [], '',
        'template id'
    )
];

# to send a batch with default settings
(new PostmarkApi('server token'))->batch($mailings);

# manually specify chunk size {how many mailings to send in one call)
(new PostmarkApi('server token'))->batch($mailings, 100);

开发

可以在运行至少PHP 8.0的任何机器上进行开发。自行设置机器或使用提供的虚拟机。

运行测试

这里的想法是测试与Postmark API无关的任何没有副作用的东西。

$ bin/phpunit

虚拟机

如果您的计算机上没有PHP 8.0或者您想避免版本冲突等问题，虚拟机可能会有所帮助。这将在您的计算机内部创建一个模拟服务器，用于此包的开发。

在大多数情况下，这应该是不必要的。

在您的计算机上安装以下现代版本。

Git — 下载
Vagrant — 下载
VirtualBox - 下载

在仓库目录中运行以下命令。

$ git submodule update --init virtual-machine
$ vagrant up

虚拟机会初始化。之后进入虚拟机并运行测试以验证设置。

$ vagrant ssh

Welcome to Ubuntu 18.04 LTS (GNU/Linux 4.15.0-20-generic x86_64)

 * Documentation:  https://help.ubuntu.com
 * Management:     https://landscape.canonical.com
 * Support:        https://ubuntu.com/advantage

Last login: Sat Dec 26 16:29:42 2020 from 10.0.2.2
minimal-php-postmark-sdk :: /vagrant $ bin/phpunit

shawnmccool / minimal-php-postmark-sdk

维护者

详细信息