README

此软件包使在 Laravel 应用程序中与 Pwinty 图像打印 API 一起工作变得轻松。您可以下订单、添加图像并将它们提交以进行运输。您还可以在 Pwinty 控制面板配置您的回调 URL 后订阅 Pwinty webhooks。

安装

您可以通过 composer 安装此软件包。

composer require wingly/pwinty

使用方法

数据库迁移

Pwinty 服务提供程序注册了自己的数据库迁移，因此请确保在安装软件包后运行迁移。将创建一个新的订单表来保存所有用户的订单。

php artisan migrate

Pwinty 环境设置

您需要在您的 .env 文件中配置您的 Pwinty API 密钥和商户 ID。

PWINTY_APIKEY=your_pwinty_key
PWINTY_MERCHANT=your_pwinty_merchant_id

您还应将 API 环境设置为 "sandbox" 或 "production"。

PWINTY_API=sandbox

处理订单

将 Orderer 特性添加到您的模型中。该特性提供了创建和检索订单的方法。

use Wingly\Pwinty\Orderer;

class User extends Authenticatable
{
    use Orderer;
}

默认情况下使用 App\User 模型。您可以通过在 .env 文件中指定不同的模型来更改此设置。

PWINTY_MODEL=App\User

创建订单

要创建新的订单，首先获取您的订单模型实例，并使用 newOrder 方法创建订单。此方法将返回一个 OrderBuilder 实例，您可以在其中设置订单参数。您应通过最后调用 create 方法来完成订单。请参阅 Pwinty 文档了解所有可用参数。

$user = User::first();

$user->newOrder()
    ->setRecipientName('John Doe')
    ->setCountryCode('FR')
    ->create();

将图像添加到订单中

创建订单后，您可以通过在您的 Order 实例上调用 addImage 方法将图像添加到订单中。此方法需要此图像产品的识别代码和图像的 URL。您可以通过链式调用 addImage 方法将多个图像添加到订单中。

$order = Order::first();

$order->addImage(
    'ART-PRI-HPG-20X28-PRODIGI_GB', 
    'https://testserver.com/aphoto.jpg'
);

提交订单

准备好后，您可以提交订单以供 Pwinty 处理。首先将检查订单的有效性，然后提交。如果订单尚未准备好提交，将抛出 OrderUpdateFailure 异常。您可以通过在您的 Order 实例上调用 submitted 方法来检查订单是否已提交。

$order = Order::first();

$order->submit();

$order->fresh()->submitted(); // true

取消订单

您可以在任何时候通过调用您的 Order 实例上的 cancel 方法来取消一个正在进行的订单。如果订单状态不可取消，将抛出 OrderUpdateFailure 异常。您可以通过调用 cancelled 方法来检查订单是否已取消。

$order = Order::first();

$order->cancel();

$order->fresh()->cancelled(); // true

更新订单

您可以通过调用您的 Order 实例上的 updatePwintyOrder 方法来更新任何正在进行的订单属性。如果订单状态不可更新，将抛出 OrderUpdateFailure 异常。该方法将返回原始的 Pwinty 订单对象。

$order = Order::first();

$pwintyOrder = $order->updatePwintyOrder(['recipientName' => 'John Doe']);

获取原始 Pwinty 订单

您可以通过调用您的 Order 实例上的 asPwintyOrder 方法来获取原始 Pwinty 订单对象。请查看 Pwinty 文档了解示例响应。

$order = Order::first();

$pwintyOrder = $order->asPwintyOrder();

处理 Pwinty Webhooks

Pwinty 在您的订单状态发生变化时可以向自定义 URL 进行回调。默认情况下，通过 Pwinty 服务提供商配置了一个指向 webhook 控制器的路由。所有传入的 Pwinty webhook 请求都将在此处处理。确保您已在 Pwinty 仪表板的集成部分设置了您的回调 URL。webhook 控制器监听 pwinty/webhook URL 路径。

签名 Webhook URL

为了保护您的 webhook，您必须在 Pwinty 仪表板上添加一个签名 URL。为了方便，该包包含一个控制台命令，可以为您生成安全的 URL。复制签名 URL 并将其添加到 Pwinty 仪表板。有一个中间件用于验证签名的路由请求。

php artisan pwinty:sign

CSRF 保护

您需要将 URI 列为应用程序中包含在 VerifyCsrfToken 中间件中的异常。

class VerifyCsrfToken extends Middleware
{
    /**
     * The URIs that should be excluded from CSRF verification.
     *
     * @var array
     */
    protected $except = [
        'pwinty/*'
    ];
}

事件

当 webhook 被处理时，该包将发出 Wingly\Pwinty\Events\WebhookProcessed 事件。该事件包含 Pwinty webhook 的完整负载。如果您的应用程序需要在收到 webhook 时采取任何操作，则可以监听此事件。

变更日志

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

贡献

请参阅 contributing.md 以获取详细信息。

致谢

许可

MIT 许可证 (MIT)。请参阅许可文件以获取更多信息。

wingly / pwinty

维护者

详情