跳转到内容
Laravel

Laravel Cashier (Paddle)

介绍

exclamation

本文档适用于 Cashier Paddle 2.x 与 Paddle Billing 的集成。如果您仍在使用 Paddle Classic，则应使用 Cashier Paddle 1.x。

Laravel Cashier Paddle 为 Paddle 的订阅计费服务提供了一个富有表现力、流畅的接口。它处理了您所厌倦的几乎所有样板订阅计费代码。除了基本的订阅管理之外，Cashier 还可以处理：交换订阅、订阅“数量”、订阅暂停、取消宽限期等等。

在深入了解 Cashier Paddle 之前，我们建议您也查看 Paddle 的概念指南和 API 文档。

升级 Cashier

升级到新版本的 Cashier 时，请务必仔细阅读升级指南。

安装

首先，使用 Composer 包管理器为 Paddle 安装 Cashier 包

composer require laravel/cashier-paddle

接下来，您应该使用 vendor:publish Artisan 命令发布 Cashier 迁移文件

php artisan vendor:publish --tag="cashier-migrations"

然后，您应该运行应用程序的数据库迁移。Cashier 迁移将创建一个新的 customers 表。此外，还将创建新的 subscriptions 和 subscription_items 表来存储所有客户的订阅。最后，将创建一个新的 transactions 表来存储与您的客户关联的所有 Paddle 交易

php artisan migrate
exclamation

为确保 Cashier 正确处理所有 Paddle 事件，请记住设置 Cashier 的 webhook 处理。

Paddle 沙箱

在本地和暂存开发期间，您应该注册一个 Paddle 沙箱帐户。此帐户将为您提供一个沙箱环境，以测试和开发您的应用程序，而无需进行实际付款。您可以使用 Paddle 的测试卡号来模拟各种支付场景。

使用 Paddle 沙箱环境时，您应该在应用程序的 .env 文件中将 PADDLE_SANDBOX 环境变量设置为 true

PADDLE_SANDBOX=true

完成应用程序开发后，您可以申请 Paddle 供应商帐户。在将您的应用程序投入生产之前，Paddle 需要批准您应用程序的域名。

配置

可计费模型

在使用 Cashier 之前，您必须将 Billable trait 添加到用户模型定义中。此 trait 提供了各种方法，使您可以执行常见的计费任务，例如创建订阅和更新付款方式信息

use Laravel\Paddle\Billable;
 
class User extends Authenticatable
{
    use Billable;
}

如果您有非用户的可计费实体，也可以将该 trait 添加到这些类中

use Illuminate\Database\Eloquent\Model;
use Laravel\Paddle\Billable;
 
class Team extends Model
{
    use Billable;
}

API 密钥

接下来，您应该在应用程序的 .env 文件中配置您的 Paddle 密钥。您可以从 Paddle 控制面板检索您的 Paddle API 密钥

PADDLE_CLIENT_SIDE_TOKEN=your-paddle-client-side-token
PADDLE_API_KEY=your-paddle-api-key
PADDLE_RETAIN_KEY=your-paddle-retain-key
PADDLE_WEBHOOK_SECRET="your-paddle-webhook-secret"
PADDLE_SANDBOX=true

当您使用Paddle 的沙箱环境时，PADDLE_SANDBOX 环境变量应设置为 true。如果您将应用程序部署到生产环境并使用 Paddle 的实时供应商环境，则应将 PADDLE_SANDBOX 变量设置为 false。

PADDLE_RETAIN_KEY 是可选的，仅当您将 Paddle 与 Retain 一起使用时才应设置。

Paddle JS

Paddle 依赖于自己的 JavaScript 库来启动 Paddle 结帐小部件。您可以通过在应用程序布局的结束 </head> 标签之前放置 @paddleJS Blade 指令来加载 JavaScript 库

<head>
    ...
 
    @paddleJS
</head>

货币配置

您可以指定一个区域设置，以便在发票上显示金额值时使用。在内部，Cashier 利用 PHP 的 NumberFormatter 类来设置货币区域设置

CASHIER_CURRENCY_LOCALE=nl_BE
exclamation

为了使用 en 以外的区域设置，请确保在您的服务器上安装并配置了 ext-intl PHP 扩展。

覆盖默认模型

您可以自由地扩展 Cashier 内部使用的模型，方法是定义您自己的模型并扩展相应的 Cashier 模型

use Laravel\Paddle\Subscription as CashierSubscription;
 
class Subscription extends CashierSubscription
{
    // ...
}

定义模型后，您可以指示 Cashier 通过 Laravel\Paddle\Cashier 类使用您的自定义模型。通常，您应该在应用程序的 App\Providers\AppServiceProvider 类的 boot 方法中告知 Cashier 您的自定义模型

use App\Models\Cashier\Subscription;
use App\Models\Cashier\Transaction;
 
/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Cashier::useSubscriptionModel(Subscription::class);
    Cashier::useTransactionModel(Transaction::class);
}

快速入门

销售产品

lightbulb

在使用 Paddle Checkout 之前，您应该在 Paddle 仪表板中定义具有固定价格的产品。此外，您应该配置 Paddle 的 webhook 处理。

通过您的应用程序提供产品和订阅计费可能会令人望而生畏。但是，借助 Cashier 和 Paddle 的结帐覆盖，您可以轻松构建现代、强大的支付集成。

要向客户收取非重复的、单次收费的产品的费用，我们将利用 Cashier 通过 Paddle 的结帐覆盖向客户收费，他们将在其中提供付款详细信息并确认购买。通过结帐覆盖付款后，客户将被重定向到您在应用程序中选择的成功 URL

use Illuminate\Http\Request;
 
Route::get('/buy', function (Request $request) {
    $checkout = $request->user()->checkout('pri_deluxe_album')
        ->returnTo(route('dashboard'));
 
    return view('buy', ['checkout' => $checkout]);
})->name('checkout');

正如您在上面的示例中看到的，我们将利用 Cashier 提供的 checkout 方法来创建一个结帐对象，以便向客户展示给定“价格标识符”的 Paddle 结帐覆盖。使用 Paddle 时，“价格”指的是为特定产品定义的价格。

如有必要，checkout 方法将自动在 Paddle 中创建一个客户，并将该 Paddle 客户记录连接到应用程序数据库中相应的用户。完成结帐会话后，客户将被重定向到专用成功页面，您可以在其中向客户显示信息性消息。

在 buy 视图中，我们将包含一个按钮来显示结帐覆盖。paddle-button Blade 组件包含在 Cashier Paddle 中；但是，您也可以手动渲染覆盖式结帐

<x-paddle-button :checkout="$checkout" class="px-8 py-4">
    Buy Product
</x-paddle-button>

向 Paddle 结帐提供元数据

在销售产品时，通常会通过您自己的应用程序定义的 Cart 和 Order 模型来跟踪已完成的订单和购买的产品。当将客户重定向到 Paddle 的结账覆盖层以完成购买时，您可能需要提供一个现有的订单标识符，以便在客户被重定向回您的应用程序时，您可以将完成的购买与相应的订单关联起来。

为了实现这一点，您可以向 checkout 方法提供一个自定义数据数组。假设当用户开始结账流程时，在我们的应用程序中创建了一个待处理的 Order。请记住，本示例中的 Cart 和 Order 模型仅用于说明，并非由 Cashier 提供。您可以根据自己应用程序的需求自由地实现这些概念。

use App\Models\Cart;
use App\Models\Order;
use Illuminate\Http\Request;
 
Route::get('/cart/{cart}/checkout', function (Request $request, Cart $cart) {
    $order = Order::create([
        'cart_id' => $cart->id,
        'price_ids' => $cart->price_ids,
        'status' => 'incomplete',
    ]);
 
    $checkout = $request->user()->checkout($order->price_ids)
        ->customData(['order_id' => $order->id]);
 
    return view('billing', ['checkout' => $checkout]);
})->name('checkout');

正如您在上面的示例中看到的，当用户开始结账流程时，我们将把所有购物车/订单关联的 Paddle 价格标识符提供给 checkout 方法。当然，您的应用程序负责在客户添加商品时将这些商品与“购物车”或订单关联起来。我们还通过 customData 方法将订单的 ID 提供给 Paddle 结账覆盖层。

当然，您可能希望在客户完成结账流程后将订单标记为“已完成”。为了实现这一点，您可以监听 Paddle 分发的 webhook，并通过 Cashier 触发的事件将订单信息存储在您的数据库中。

首先，监听 Cashier 分发的 TransactionCompleted 事件。通常，您应该在应用程序的 AppServiceProvider 的 boot 方法中注册事件监听器。

use App\Listeners\CompleteOrder;
use Illuminate\Support\Facades\Event;
use Laravel\Paddle\Events\TransactionCompleted;
 
/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Event::listen(TransactionCompleted::class, CompleteOrder::class);
}

在本示例中，CompleteOrder 监听器可能如下所示

namespace App\Listeners;
 
use App\Models\Order;
use Laravel\Paddle\Cashier;
use Laravel\Paddle\Events\TransactionCompleted;
 
class CompleteOrder
{
    /**
     * Handle the incoming Cashier webhook event.
     */
    public function handle(TransactionCompleted $event): void
    {
        $orderId = $event->payload['data']['custom_data']['order_id'] ?? null;
 
        $order = Order::findOrFail($orderId);
 
        $order->update(['status' => 'completed']);
    }
}

请参阅 Paddle 的文档，了解有关 transaction.completed 事件包含的数据的更多信息。

销售订阅

lightbulb

在使用 Paddle Checkout 之前，您应该在 Paddle 仪表板中定义具有固定价格的产品。此外，您应该配置 Paddle 的 webhook 处理。

通过您的应用程序提供产品和订阅计费可能会令人望而生畏。但是，借助 Cashier 和 Paddle 的结帐覆盖，您可以轻松构建现代、强大的支付集成。

要了解如何使用 Cashier 和 Paddle 的结账覆盖层销售订阅，让我们考虑一个简单的场景，即一个具有基本月度计划 (price_basic_monthly) 和年度计划 (price_basic_yearly) 的订阅服务。这两个价格可以在我们的 Paddle 仪表板中归入“基本”产品 (pro_basic) 下。此外，我们的订阅服务可能提供一个专家计划，即 pro_expert。

首先，让我们了解客户如何订阅我们的服务。当然，您可以想象客户可能会在我们的应用程序定价页面上点击基本计划的“订阅”按钮。此按钮将为其选择的计划调用 Paddle 结账覆盖层。首先，让我们通过 checkout 方法启动一个结账会话

use Illuminate\Http\Request;
 
Route::get('/subscribe', function (Request $request) {
    $checkout = $request->user()->checkout('price_basic_monthly')
        ->returnTo(route('dashboard'));
 
    return view('subscribe', ['checkout' => $checkout]);
})->name('subscribe');

在 subscribe 视图中，我们将包含一个按钮来显示结账覆盖层。paddle-button Blade 组件包含在 Cashier Paddle 中；但是，您也可以手动渲染覆盖层结账

<x-paddle-button :checkout="$checkout" class="px-8 py-4">
    Subscribe
</x-paddle-button>

现在，当点击“订阅”按钮时，客户将能够输入他们的付款详细信息并开始他们的订阅。要知道他们的订阅何时真正开始（因为某些付款方式需要几秒钟才能处理），您还应该配置 Cashier 的 webhook 处理。

现在客户可以开始订阅了，我们需要限制我们应用程序的某些部分，以便只有订阅用户才能访问它们。当然，我们始终可以通过 Cashier 的 Billable trait 提供的 subscribed 方法来确定用户的当前订阅状态

@if ($user->subscribed())
    <p>You are subscribed.</p>
@endif

我们甚至可以轻松确定用户是否订阅了特定产品或价格

@if ($user->subscribedToProduct('pro_basic'))
    <p>You are subscribed to our Basic product.</p>
@endif
 
@if ($user->subscribedToPrice('price_basic_monthly'))
    <p>You are subscribed to our monthly Basic plan.</p>
@endif

构建订阅中间件

为了方便起见，您可能希望创建一个中间件，以确定传入的请求是否来自订阅用户。一旦定义了此中间件，您就可以轻松地将其分配给路由，以防止未订阅的用户访问该路由

<?php
 
namespace App\Http\Middleware;
 
use Closure;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;
 
class Subscribed
{
    /**
     * Handle an incoming request.
     */
    public function handle(Request $request, Closure $next): Response
    {
        if (! $request->user()?->subscribed()) {
            // Redirect user to billing page and ask them to subscribe...
            return redirect('/subscribe');
        }
 
        return $next($request);
    }
}

定义中间件后，您可以将其分配给路由

use App\Http\Middleware\Subscribed;
 
Route::get('/dashboard', function () {
    // ...
})->middleware([Subscribed::class]);

允许客户管理他们的账单计划

当然，客户可能希望将其订阅计划更改为其他产品或“层级”。在我们上面的示例中，我们希望允许客户将其计划从每月订阅更改为年度订阅。为此，您需要实现一个类似按钮的东西，该按钮指向以下路由

use Illuminate\Http\Request;
 
Route::put('/subscription/{price}/swap', function (Request $request, $price) {
    $user->subscription()->swap($price); // With "$price" being "price_basic_yearly" for this example.
 
    return redirect()->route('dashboard');
})->name('subscription.swap');

除了交换计划之外，您还需要允许您的客户取消他们的订阅。与交换计划一样，提供一个指向以下路由的按钮

use Illuminate\Http\Request;
 
Route::put('/subscription/cancel', function (Request $request, $price) {
    $user->subscription()->cancel();
 
    return redirect()->route('dashboard');
})->name('subscription.cancel');

现在您的订阅将在其账单周期结束时被取消。

lightbulb

只要您配置了 Cashier 的 webhook 处理，Cashier 就会通过检查来自 Paddle 的传入 webhook 自动保持您的应用程序中与 Cashier 相关的数据库表同步。因此，例如，当您通过 Paddle 的仪表板取消客户的订阅时，Cashier 将收到相应的 webhook 并在您的应用程序数据库中将订阅标记为“已取消”。

结账会话

大多数向客户收费的操作都是使用 Paddle 的 结账覆盖层小部件 或使用 内联结账执行的。

在使用 Paddle 处理结账付款之前，您应该在 Paddle 结账设置仪表板中定义您的应用程序的默认付款链接。

覆盖式结账

在显示结账覆盖层小部件之前，您必须使用 Cashier 生成一个结账会话。结账会话将告知结账小部件应执行的账单操作

use Illuminate\Http\Request;
 
Route::get('/buy', function (Request $request) {
    $checkout = $user->checkout('pri_34567')
        ->returnTo(route('dashboard'));
 
    return view('billing', ['checkout' => $checkout]);
});

Cashier 包括一个 paddle-button Blade 组件。您可以将结账会话作为“prop”传递给此组件。然后，当单击此按钮时，将显示 Paddle 的结账小部件

<x-paddle-button :checkout="$checkout" class="px-8 py-4">
    Subscribe
</x-paddle-button>

默认情况下，这将使用 Paddle 的默认样式显示小部件。您可以通过向组件添加 Paddle 支持的属性（例如 data-theme='light' 属性）来自定义小部件

<x-paddle-button :url="$payLink" class="px-8 py-4" data-theme="light">
    Subscribe
</x-paddle-button>

Paddle 结账小部件是异步的。一旦用户在小部件中创建订阅，Paddle 将向您的应用程序发送一个 webhook，以便您可以正确更新应用程序数据库中的订阅状态。因此，正确设置 webhook 以适应 Paddle 的状态更改非常重要。

exclamation

在订阅状态更改后，接收相应 webhook 的延迟通常很小，但您应该在应用程序中考虑这一点，并考虑到用户的订阅在完成结账后可能无法立即使用。

手动渲染覆盖层结账

您也可以手动渲染覆盖层结账，而无需使用 Laravel 内置的 Blade 组件。首先，如前面的示例所示生成结账会话

use Illuminate\Http\Request;
 
Route::get('/buy', function (Request $request) {
    $checkout = $user->checkout('pri_34567')
        ->returnTo(route('dashboard'));
 
    return view('billing', ['checkout' => $checkout]);
});

接下来，您可以使用 Paddle.js 初始化结账。在本示例中，我们将创建一个被分配了 paddle_button 类的链接。Paddle.js 将检测到这个类并在单击该链接时显示覆盖层结账

<?php
$items = $checkout->getItems();
$customer = $checkout->getCustomer();
$custom = $checkout->getCustomData();
?>
 
<a
    href='#!'
    class='paddle_button'
    data-items='{!! json_encode($items) !!}'
    @if ($customer) data-customer-id='{{ $customer->paddle_id }}' @endif
    @if ($custom) data-custom-data='{{ json_encode($custom) }}' @endif
    @if ($returnUrl = $checkout->getReturnUrl()) data-success-url='{{ $returnUrl }}' @endif
>
    Buy Product
</a>

内联结账

如果您不想使用 Paddle 的“覆盖层”样式结账小部件，Paddle 还提供了在内联显示小部件的选项。虽然此方法不允许您调整结账的任何 HTML 字段，但它允许您将小部件嵌入到您的应用程序中。

为了方便您开始使用内联结账，Cashier 包括一个 paddle-checkout Blade 组件。首先，您应该生成一个结账会话

use Illuminate\Http\Request;
 
Route::get('/buy', function (Request $request) {
    $checkout = $user->checkout('pri_34567')
        ->returnTo(route('dashboard'));
 
    return view('billing', ['checkout' => $checkout]);
});

然后，您可以将结账会话传递给组件的 checkout 属性

<x-paddle-checkout :checkout="$checkout" class="w-full" />

要调整内联结账组件的高度，您可以将 height 属性传递给 Blade 组件

<x-paddle-checkout :checkout="$checkout" class="w-full" height="500" />

请参阅 Paddle 的内联结账指南和可用结账设置，了解有关内联结账的自定义选项的更多详细信息。

手动渲染内联结账

您也可以手动渲染内联结账，而无需使用 Laravel 内置的 Blade 组件。首先，如前面的示例所示生成结账会话

use Illuminate\Http\Request;
 
Route::get('/buy', function (Request $request) {
    $checkout = $user->checkout('pri_34567')
        ->returnTo(route('dashboard'));
 
    return view('billing', ['checkout' => $checkout]);
});

接下来，您可以使用 Paddle.js 初始化结账。在本示例中，我们将使用 Alpine.js 来演示这一点；但是，您可以自由地为自己的前端堆栈修改此示例

<?php
$options = $checkout->options();
 
$options['settings']['frameTarget'] = 'paddle-checkout';
$options['settings']['frameInitialHeight'] = 366;
?>
 
<div class="paddle-checkout" x-data="{}" x-init="
    Paddle.Checkout.open(@json($options));
">
</div>

访客结账

有时，您可能需要为不需要在您的应用程序中创建帐户的用户创建结账会话。为此，您可以使用 guest 方法

use Illuminate\Http\Request;
use Laravel\Paddle\Checkout;
 
Route::get('/buy', function (Request $request) {
    $checkout = Checkout::guest('pri_34567')
        ->returnTo(route('home'));
 
    return view('billing', ['checkout' => $checkout]);
});

然后，您可以将结账会话提供给Paddle 按钮或内联结账 Blade 组件。

价格预览

Paddle 允许您自定义每种货币的价格，这实际上允许您为不同的国家/地区配置不同的价格。Cashier Paddle 允许您使用 previewPrices 方法检索所有这些价格。此方法接受您要检索价格的价格 ID

use Laravel\Paddle\Cashier;
 
$prices = Cashier::previewPrices(['pri_123', 'pri_456']);

货币将根据请求的 IP 地址确定；但是，您可以选择提供一个特定的国家/地区来检索价格

use Laravel\Paddle\Cashier;
 
$prices = Cashier::previewPrices(['pri_123', 'pri_456'], ['address' => [
    'country_code' => 'BE',
    'postal_code' => '1234',
]]);

检索价格后，您可以随意显示它们

<ul>
    @foreach ($prices as $price)
        <li>{{ $price->product['name'] }} - {{ $price->total() }}</li>
    @endforeach
</ul>

您还可以单独显示小计价格和税额

<ul>
    @foreach ($prices as $price)
        <li>{{ $price->product['name'] }} - {{ $price->subtotal() }} (+ {{ $price->tax() }} tax)</li>
    @endforeach
</ul>

有关更多信息，请查看 Paddle 关于价格预览的 API 文档。

客户价格预览

如果用户已经是客户，并且您想显示适用于该客户的价格，您可以通过直接从客户实例检索价格来实现

use App\Models\User;
 
$prices = User::find(1)->previewPrices(['pri_123', 'pri_456']);

在内部，Cashier 将使用用户的客户 ID 来检索其货币的价格。因此，例如，居住在美国的用户将看到美元价格，而居住在比利时的用户将看到欧元价格。如果找不到匹配的货币，则将使用产品的默认货币。您可以在 Paddle 控制面板中自定义产品或订阅计划的所有价格。

折扣

您也可以选择在折扣后显示价格。当调用 previewPrices 方法时，您可以通过 discount_id 选项提供折扣 ID

use Laravel\Paddle\Cashier;
 
$prices = Cashier::previewPrices(['pri_123', 'pri_456'], [
    'discount_id' => 'dsc_123'
]);

然后，显示计算出的价格

<ul>
    @foreach ($prices as $price)
        <li>{{ $price->product['name'] }} - {{ $price->total() }}</li>
    @endforeach
</ul>

客户

客户默认值

Cashier 允许您在创建结账会话时为您的客户定义一些有用的默认值。设置这些默认值允许您预先填写客户的电子邮件地址和姓名，以便他们可以立即进入结账小部件的付款部分。您可以通过覆盖可计费模型上的以下方法来设置这些默认值

/**
 * Get the customer's name to associate with Paddle.
 */
public function paddleName(): string|null
{
    return $this->name;
}
 
/**
 * Get the customer's email address to associate with Paddle.
 */
public function paddleEmail(): string|null
{
    return $this->email;
}

这些默认值将用于 Cashier 中生成结账会话的每个操作。

检索客户

您可以使用 Cashier::findBillable 方法通过他们的 Paddle 客户 ID 检索客户。此方法将返回可计费模型的实例

use Laravel\Paddle\Cashier;
 
$user = Cashier::findBillable($customerId);

创建客户

有时，您可能希望在不开始订阅的情况下创建 Paddle 客户。您可以使用 createAsCustomer 方法来实现此目的

$customer = $user->createAsCustomer();

将返回 Laravel\Paddle\Customer 的实例。在 Paddle 中创建客户后，您可以在稍后开始订阅。您可以提供一个可选的 $options 数组来传入 Paddle API 支持的任何其他客户创建参数

$customer = $user->createAsCustomer($options);

订阅

创建订阅

要创建订阅，首先从您的数据库中检索可计费模型的实例，这通常是 App\Models\User 的实例。检索模型实例后，您可以使用 subscribe 方法来创建模型的结账会话

use Illuminate\Http\Request;
 
Route::get('/user/subscribe', function (Request $request) {
    $checkout = $request->user()->subscribe($premium = 12345, 'default')
        ->returnTo(route('home'));
 
    return view('billing', ['checkout' => $checkout]);
});

传递给 subscribe 方法的第一个参数是用户正在订阅的特定价格。此值应与 Paddle 中价格的标识符相对应。 returnTo 方法接受一个 URL，用户在成功完成结账后将被重定向到该 URL。传递给 subscribe 方法的第二个参数应该是订阅的内部“类型”。如果您的应用程序仅提供单个订阅，则可以将其称为 default 或 primary 。此订阅类型仅用于内部应用程序使用，不应向用户显示。此外，它不应包含空格，并且在创建订阅后绝不应更改。

您还可以使用 customData 方法提供有关订阅的自定义元数据数组

$checkout = $request->user()->subscribe($premium = 12345, 'default')
    ->customData(['key' => 'value'])
    ->returnTo(route('home'));

创建订阅结账会话后，可以将结账会话提供给 Cashier Paddle 中包含的 paddle-button Blade 组件

<x-paddle-button :checkout="$checkout" class="px-8 py-4">
    Subscribe
</x-paddle-button>

用户完成结账后，Paddle 将分派一个 subscription_created webhook。Cashier 将接收此 webhook 并为您的客户设置订阅。为了确保您的应用程序正确接收和处理所有 webhook，请确保您已正确设置 webhook 处理。

检查订阅状态

一旦用户订阅了您的应用程序，您可以使用各种方便的方法来检查他们的订阅状态。首先，如果用户具有有效的订阅，即使该订阅当前处于试用期内，subscribed 方法也会返回 true

if ($user->subscribed()) {
    // ...
}

如果您的应用程序提供多个订阅，您可以在调用 subscribed 方法时指定订阅

if ($user->subscribed('default')) {
    // ...
}

subscribed 方法也是路由中间件的理想候选，允许您根据用户的订阅状态来筛选对路由和控制器的访问

<?php
 
namespace App\Http\Middleware;
 
use Closure;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;
 
class EnsureUserIsSubscribed
{
    /**
     * Handle an incoming request.
     *
     * @param  \Closure(\Illuminate\Http\Request): (\Symfony\Component\HttpFoundation\Response)  $next
     */
    public function handle(Request $request, Closure $next): Response
    {
        if ($request->user() && ! $request->user()->subscribed()) {
            // This user is not a paying customer...
            return redirect('/billing');
        }
 
        return $next($request);
    }
}

如果您想确定用户是否仍在试用期内，您可以使用 onTrial 方法。此方法可用于确定您是否应该向用户显示他们仍在试用期的警告

if ($user->subscription()->onTrial()) {
    // ...
}

可以使用 subscribedToPrice 方法来确定用户是否根据给定的 Paddle 价格 ID 订阅了给定的计划。在此示例中，我们将确定用户的 default 订阅是否已有效订阅每月价格

if ($user->subscribedToPrice($monthly = 'pri_123', 'default')) {
    // ...
}

可以使用 recurring 方法来确定用户当前是否处于有效订阅状态，并且不再处于试用期或宽限期

if ($user->subscription()->recurring()) {
    // ...
}

已取消的订阅状态

要确定用户是否曾经是有效的订阅者但已取消订阅，您可以使用 canceled 方法

if ($user->subscription()->canceled()) {
    // ...
}

您还可以确定用户是否已取消订阅，但仍处于“宽限期”，直到订阅完全过期。例如，如果用户在 3 月 5 日取消了原定于 3 月 10 日到期的订阅，则用户将处于“宽限期”，直到 3 月 10 日。此外，subscribed 方法在此期间仍将返回 true

if ($user->subscription()->onGracePeriod()) {
    // ...
}

过期未付状态

如果订阅的付款失败，它将被标记为 past_due。当您的订阅处于此状态时，在客户更新其付款信息之前，它不会处于活动状态。您可以使用订阅实例上的 pastDue 方法来确定订阅是否已过期

if ($user->subscription()->pastDue()) {
    // ...
}

当订阅过期未付时，您应该指示用户更新其付款信息。

如果您希望订阅在 past_due 时仍然被认为是有效的，则可以使用 Cashier 提供的 keepPastDueSubscriptionsActive 方法。通常，此方法应在您的 AppServiceProvider 的 register 方法中调用

use Laravel\Paddle\Cashier;
 
/**
 * Register any application services.
 */
public function register(): void
{
    Cashier::keepPastDueSubscriptionsActive();
}
exclamation

当订阅处于 past_due 状态时，在付款信息更新之前无法更改。因此，当订阅处于 past_due 状态时，swap 和 updateQuantity 方法将抛出异常。

订阅范围

大多数订阅状态也可作为查询范围使用，以便您可以轻松地在数据库中查询处于给定状态的订阅

// Get all valid subscriptions...
$subscriptions = Subscription::query()->valid()->get();
 
// Get all of the canceled subscriptions for a user...
$subscriptions = $user->subscriptions()->canceled()->get();

可用范围的完整列表如下

Subscription::query()->valid();
Subscription::query()->onTrial();
Subscription::query()->expiredTrial();
Subscription::query()->notOnTrial();
Subscription::query()->active();
Subscription::query()->recurring();
Subscription::query()->pastDue();
Subscription::query()->paused();
Subscription::query()->notPaused();
Subscription::query()->onPausedGracePeriod();
Subscription::query()->notOnPausedGracePeriod();
Subscription::query()->canceled();
Subscription::query()->notCanceled();
Subscription::query()->onGracePeriod();
Subscription::query()->notOnGracePeriod();

订阅单次收费

订阅单次收费允许您在订阅的基础上向订阅者收取一次性费用。您必须在调用 charge 方法时提供一个或多个价格 ID

// Charge a single price...
$response = $user->subscription()->charge('pri_123');
 
// Charge multiple prices at once...
$response = $user->subscription()->charge(['pri_123', 'pri_456']);

charge 方法实际上不会向客户收费，直到他们订阅的下一个结算周期。如果您想立即向客户收费，则可以使用 chargeAndInvoice 方法代替

$response = $user->subscription()->chargeAndInvoice('pri_123');

更新支付信息

Paddle 始终为每个订阅保存一种付款方式。如果要更新订阅的默认付款方式，您应该使用订阅模型上的 redirectToUpdatePaymentMethod 方法将客户重定向到 Paddle 的托管付款方式更新页面

use Illuminate\Http\Request;
 
Route::get('/update-payment-method', function (Request $request) {
    $user = $request->user();
 
    return $user->subscription()->redirectToUpdatePaymentMethod();
});

用户完成信息更新后，Paddle 将分派一个 subscription_updated webhook，并且订阅详细信息将在您应用程序的数据库中更新。

更改套餐

用户订阅您的应用程序后，他们有时可能希望更改为新的订阅计划。要更新用户的订阅计划，您应该将 Paddle 价格的标识符传递给订阅的 swap 方法

use App\Models\User;
 
$user = User::find(1);
 
$user->subscription()->swap($premium = 'pri_456');

如果您想更换计划并立即向用户开具发票，而不是等待他们的下一个结算周期，则可以使用 swapAndInvoice 方法

$user = User::find(1);
 
$user->subscription()->swapAndInvoice($premium = 'pri_456');

按比例收费

默认情况下，在计划之间更换时，Paddle 会按比例收取费用。可以使用 noProrate 方法更新订阅，而不按比例收取费用

$user->subscription('default')->noProrate()->swap($premium = 'pri_456');

如果您想禁用按比例收费并立即向客户开具发票，则可以将 swapAndInvoice 方法与 noProrate 结合使用

$user->subscription('default')->noProrate()->swapAndInvoice($premium = 'pri_456');

或者，为了不向客户收取订阅更改的费用，您可以使用 doNotBill 方法

$user->subscription('default')->doNotBill()->swap($premium = 'pri_456');

有关 Paddle 按比例收费策略的更多信息，请参阅 Paddle 的按比例收费文档。

订阅数量

有时，订阅会受到“数量”的影响。例如，项目管理应用程序可能会按每个项目每月收取 10 美元。要轻松增加或减少订阅的数量，请使用 incrementQuantity 和 decrementQuantity 方法

$user = User::find(1);
 
$user->subscription()->incrementQuantity();
 
// Add five to the subscription's current quantity...
$user->subscription()->incrementQuantity(5);
 
$user->subscription()->decrementQuantity();
 
// Subtract five from the subscription's current quantity...
$user->subscription()->decrementQuantity(5);

或者，您可以使用 updateQuantity 方法设置特定数量

$user->subscription()->updateQuantity(10);

可以使用 noProrate 方法更新订阅的数量，而不按比例收取费用

$user->subscription()->noProrate()->updateQuantity(10);

具有多个产品的订阅的数量

如果您的订阅是具有多个产品的订阅，则应将您要增加或减少其数量的价格 ID 作为第二个参数传递给增量/减量方法

$user->subscription()->incrementQuantity(1, 'price_chat');

具有多个产品的订阅

具有多个产品的订阅允许您将多个计费产品分配给单个订阅。例如，假设您正在构建一个客户服务“帮助台”应用程序，该应用程序的基本订阅价格为每月 10 美元，但提供每月额外 15 美元的实时聊天附加产品。

在创建订阅结账会话时，您可以通过将价格数组作为 subscribe 方法的第一个参数来为给定订阅指定多个产品

use Illuminate\Http\Request;
 
Route::post('/user/subscribe', function (Request $request) {
    $checkout = $request->user()->subscribe([
        'price_monthly',
        'price_chat',
    ]);
 
    return view('billing', ['checkout' => $checkout]);
});

在上面的示例中，客户将有两个价格附加到他们的 default 订阅。两个价格都将按其各自的结算间隔收费。如有必要，您可以传递键/值对的关联数组，以指示每个价格的特定数量

$user = User::find(1);
 
$checkout = $user->subscribe('default', ['price_monthly', 'price_chat' => 5]);

如果您想向现有订阅添加另一个价格，则必须使用订阅的 swap 方法。调用 swap 方法时，您还应包括订阅的当前价格和数量

$user = User::find(1);
 
$user->subscription()->swap(['price_chat', 'price_original' => 2]);

上面的示例将添加新价格，但客户不会在其下一个结算周期之前为此付费。如果您想立即向客户收费，则可以使用 swapAndInvoice 方法

$user->subscription()->swapAndInvoice(['price_chat', 'price_original' => 2]);

您可以使用 swap 方法从订阅中删除价格，并省略要删除的价格

$user->subscription()->swap(['price_original' => 2]);
exclamation

您不能删除订阅上的最后一个价格。相反，您应该直接取消订阅。

多个订阅

Paddle 允许您的客户同时拥有多个订阅。例如，您可能经营一家健身房，提供游泳订阅和举重订阅，并且每个订阅的价格可能不同。当然，客户应该能够订阅其中一项或两项计划。

当您的应用程序创建订阅时，您可以在 subscribe 方法中提供订阅的类型作为第二个参数。该类型可以是任何代表用户正在启动的订阅类型的字符串

use Illuminate\Http\Request;
 
Route::post('/swimming/subscribe', function (Request $request) {
    $checkout = $request->user()->subscribe($swimmingMonthly = 'pri_123', 'swimming');
 
    return view('billing', ['checkout' => $checkout]);
});

在此示例中，我们为客户启动了每月游泳订阅。但是，他们可能希望稍后更换为年度订阅。在调整客户的订阅时，我们可以简单地更改 swimming 订阅的价格

$user->subscription('swimming')->swap($swimmingYearly = 'pri_456');

当然，您也可以完全取消订阅

$user->subscription('swimming')->cancel();

暂停订阅

要暂停订阅，请在用户的订阅上调用 pause 方法

$user->subscription()->pause();

暂停订阅后，Cashier 将自动在您的数据库中设置 paused_at 列。此列用于确定 paused 方法应何时开始返回 true。例如，如果客户在 3 月 1 日暂停了订阅，但该订阅计划在 3 月 5 日之前不会重复出现，则 paused 方法将继续返回 false，直到 3 月 5 日。这是因为通常允许用户继续使用应用程序，直到其结算周期结束。

默认情况下，暂停发生在下一个结算周期，因此客户可以使用他们已付费的剩余期间。如果您想立即暂停订阅，则可以使用 pauseNow 方法

$user->subscription()->pauseNow();

使用 pauseUntil 方法，您可以将订阅暂停到特定时间

$user->subscription()->pauseUntil(now()->addMonth());

或者，您可以使用 pauseNowUntil 方法立即将订阅暂停到给定时间点

$user->subscription()->pauseNowUntil(now()->addMonth());

您可以使用 onPausedGracePeriod 方法来确定用户是否已暂停订阅但仍处于其“宽限期”内

if ($user->subscription()->onPausedGracePeriod()) {
    // ...
}

要恢复已暂停的订阅，您可以在订阅上调用 resume 方法

$user->subscription()->resume();
exclamation

订阅在暂停时无法修改。如果要更换到其他计划或更新数量，您必须先恢复订阅。

取消订阅

要取消订阅，请在用户的订阅上调用 cancel 方法

$user->subscription()->cancel();

当订阅被取消时，Cashier 会自动在您的数据库中设置 ends_at 列。此列用于确定 subscribed 方法何时开始返回 false。例如，如果客户在 3 月 1 日取消了订阅，但订阅计划在 3 月 5 日结束，则 subscribed 方法将继续返回 true，直到 3 月 5 日。这样做是因为通常允许用户在结算周期结束前继续使用应用程序。

您可以使用 onGracePeriod 方法确定用户是否已取消订阅，但仍处于“宽限期”。

if ($user->subscription()->onGracePeriod()) {
    // ...
}

如果您希望立即取消订阅，可以在订阅上调用 cancelNow 方法。

$user->subscription()->cancelNow();

要停止处于宽限期内的订阅被取消，您可以调用 stopCancelation 方法。

$user->subscription()->stopCancelation();
exclamation

Paddle 的订阅在取消后无法恢复。如果您的客户希望恢复订阅，他们必须创建一个新的订阅。

订阅试用

预先提供付款方式

如果您想为您的客户提供试用期，同时预先收集付款方式信息，您应该在 Paddle 控制面板中设置客户订阅价格的试用时间。然后，像往常一样发起结账会话。

use Illuminate\Http\Request;
 
Route::get('/user/subscribe', function (Request $request) {
    $checkout = $request->user()->subscribe('pri_monthly')
                ->returnTo(route('home'));
 
    return view('billing', ['checkout' => $checkout]);
});

当您的应用程序收到 subscription_created 事件时，Cashier 将在您应用程序数据库的订阅记录中设置试用期结束日期，并指示 Paddle 在此日期之后才开始向客户收费。

exclamation

如果客户的订阅在试用期结束日期之前未被取消，他们将在试用期结束后立即被收费，因此您应确保通知用户他们的试用期结束日期。

您可以使用用户实例的 onTrial 方法或订阅实例的 onTrial 方法来确定用户是否在试用期内。以下两个示例是等效的。

if ($user->onTrial()) {
    // ...
}
 
if ($user->subscription()->onTrial()) {
    // ...
}

要确定现有试用期是否已过期，您可以使用 hasExpiredTrial 方法。

if ($user->hasExpiredTrial()) {
    // ...
}
 
if ($user->subscription()->hasExpiredTrial()) {
    // ...
}

要确定用户是否正在特定订阅类型的试用期内，您可以将类型提供给 onTrial 或 hasExpiredTrial 方法。

if ($user->onTrial('default')) {
    // ...
}
 
if ($user->hasExpiredTrial('default')) {
    // ...
}

不预先提供付款方式

如果您想在不预先收集用户付款方式信息的情况下提供试用期，您可以在附加到用户的客户记录上设置 trial_ends_at 列为您想要的试用期结束日期。这通常在用户注册期间完成。

use App\Models\User;
 
$user = User::create([
    // ...
]);
 
$user->createAsCustomer([
    'trial_ends_at' => now()->addDays(10)
]);

Cashier 将这种类型的试用称为“通用试用”，因为它不附加到任何现有订阅。如果当前日期未超过 trial_ends_at 的值，则 User 实例上的 onTrial 方法将返回 true。

if ($user->onTrial()) {
    // User is within their trial period...
}

当您准备好为用户创建实际订阅时，您可以像往常一样使用 subscribe 方法。

use Illuminate\Http\Request;
 
Route::get('/user/subscribe', function (Request $request) {
    $checkout = $user->subscribe('pri_monthly')
        ->returnTo(route('home'));
 
    return view('billing', ['checkout' => $checkout]);
});

要检索用户的试用期结束日期，您可以使用 trialEndsAt 方法。如果用户正在试用中，此方法将返回 Carbon 日期实例，否则将返回 null。如果您想获取特定订阅（而不是默认订阅）的试用期结束日期，您还可以传递一个可选的订阅类型参数。

if ($user->onTrial('default')) {
    $trialEndsAt = $user->trialEndsAt();
}

如果您想具体了解用户是否在“通用”试用期内且尚未创建实际订阅，您可以使用 onGenericTrial 方法。

if ($user->onGenericTrial()) {
    // User is within their "generic" trial period...
}

延长或激活试用

您可以通过调用 extendTrial 方法并指定试用期应结束的时间来延长订阅的现有试用期。

$user->subscription()->extendTrial(now()->addDays(5));

或者，您可以通过在订阅上调用 activate 方法来立即激活订阅，从而结束其试用期。

$user->subscription()->activate();

处理 Paddle Webhooks

Paddle 可以通过 Webhook 通知您的应用程序各种事件。默认情况下，Cashier 服务提供商会注册一个指向 Cashier 的 Webhook 控制器的路由。此控制器将处理所有传入的 Webhook 请求。

默认情况下，此控制器将自动处理因过多失败的扣款、订阅更新和付款方式更改而取消的订阅；但是，正如我们很快将发现的那样，您可以扩展此控制器来处理您喜欢的任何 Paddle Webhook 事件。

为了确保您的应用程序可以处理 Paddle Webhook，请务必在 Paddle 控制面板中配置 Webhook URL。默认情况下，Cashier 的 Webhook 控制器响应 /paddle/webhook URL 路径。您应在 Paddle 控制面板中启用的所有 Webhook 的完整列表为：

  • 客户已更新
  • 交易已完成
  • 交易已更新
  • 订阅已创建
  • 订阅已更新
  • 订阅已暂停
  • 订阅已取消
exclamation

请确保使用 Cashier 包含的 Webhook 签名验证中间件来保护传入的请求。

Webhook 和 CSRF 保护

由于 Paddle Webhook 需要绕过 Laravel 的 CSRF 保护，您应确保 Laravel 不会尝试验证传入的 Paddle Webhook 的 CSRF 令牌。为此，您应该在应用程序的 bootstrap/app.php 文件中排除 paddle/* 的 CSRF 保护。

->withMiddleware(function (Middleware $middleware) {
    $middleware->validateCsrfTokens(except: [
        'paddle/*',
    ]);
})

Webhook 和本地开发

为了让 Paddle 能够在本地开发期间向您的应用程序发送 Webhook，您需要通过诸如 Ngrok 或 Expose 之类的站点共享服务来公开您的应用程序。如果您正在使用 Laravel Sail 在本地开发您的应用程序，则可以使用 Sail 的 站点共享命令。

定义 Webhook 事件处理程序

Cashier 会自动处理失败扣款的订阅取消和其他常见的 Paddle Webhook。但是，如果您有其他想要处理的 Webhook 事件，可以通过侦听 Cashier 派发的以下事件来执行此操作：

  • Laravel\Paddle\Events\WebhookReceived
  • Laravel\Paddle\Events\WebhookHandled

这两个事件都包含 Paddle Webhook 的完整有效负载。例如，如果您想处理 transaction.billed Webhook，您可以注册一个 侦听器来处理该事件。

<?php
 
namespace App\Listeners;
 
use Laravel\Paddle\Events\WebhookReceived;
 
class PaddleEventListener
{
    /**
     * Handle received Paddle webhooks.
     */
    public function handle(WebhookReceived $event): void
    {
        if ($event->payload['event_type'] === 'transaction.billed') {
            // Handle the incoming event...
        }
    }
}

Cashier 还发出专用于接收到的 Webhook 类型的事件。除了来自 Paddle 的完整有效负载之外，它们还包含用于处理 Webhook 的相关模型，例如可计费模型、订阅或收据。

  • Laravel\Paddle\Events\CustomerUpdated
  • Laravel\Paddle\Events\TransactionCompleted
  • Laravel\Paddle\Events\TransactionUpdated
  • Laravel\Paddle\Events\SubscriptionCreated
  • Laravel\Paddle\Events\SubscriptionUpdated
  • Laravel\Paddle\Events\SubscriptionPaused
  • Laravel\Paddle\Events\SubscriptionCanceled

您还可以通过在应用程序的 .env 文件中定义 CASHIER_WEBHOOK 环境变量来覆盖默认的内置 Webhook 路由。此值应为您的 Webhook 路由的完整 URL，并且需要与 Paddle 控制面板中设置的 URL 匹配。

CASHIER_WEBHOOK=https://example.com/my-paddle-webhook-url

验证 Webhook 签名

为了保护您的 Webhook，您可以使用 Paddle 的 Webhook 签名。为方便起见，Cashier 自动包含一个中间件，该中间件验证传入的 Paddle Webhook 请求是否有效。

要启用 Webhook 验证，请确保在应用程序的 .env 文件中定义了 PADDLE_WEBHOOK_SECRET 环境变量。Webhook 密钥可以从您的 Paddle 帐户仪表板中检索。

单次收费

产品收费

如果您想为客户发起产品购买，您可以使用可计费模型实例上的 checkout 方法来生成购买的结账会话。checkout 方法接受一个或多个价格 ID。如有必要，可以使用关联数组来提供正在购买的产品的数量。

use Illuminate\Http\Request;
 
Route::get('/buy', function (Request $request) {
    $checkout = $request->user()->checkout(['pri_tshirt', 'pri_socks' => 5]);
 
    return view('buy', ['checkout' => $checkout]);
});

生成结账会话后，您可以使用 Cashier 提供的 paddle-button Blade 组件，允许用户查看 Paddle 结账小部件并完成购买。

<x-paddle-button :checkout="$checkout" class="px-8 py-4">
    Buy
</x-paddle-button>

结账会话有一个 customData 方法，允许您将您希望的任何自定义数据传递到基础交易创建中。请查阅 Paddle 文档以了解有关传递自定义数据时可用的选项的更多信息。

$checkout = $user->checkout('pri_tshirt')
    ->customData([
        'custom_option' => $value,
    ]);

退款交易

退款交易会将退款金额退回到您的客户在购买时使用的付款方式。如果您需要退还 Paddle 购买的款项，您可以使用 Cashier\Paddle\Transaction 模型上的 refund 方法。此方法接受一个原因作为第一个参数，一个或多个要退款的价格 ID，以及可选金额作为关联数组。您可以使用 transactions 方法检索给定可计费模型的交易。

例如，假设我们要为价格 pri_123 和 pri_456 的特定交易退款。我们想全额退还 pri_123，但只退还 pri_456 两美元。

use App\Models\User;
 
$user = User::find(1);
 
$transaction = $user->transactions()->first();
 
$response = $transaction->refund('Accidental charge', [
    'pri_123', // Fully refund this price...
    'pri_456' => 200, // Only partially refund this price...
]);

上面的示例会退还交易中的特定行项目。如果要退还整个交易，只需提供一个原因。

$response = $transaction->refund('Accidental charge');

有关退款的更多信息，请参阅 Paddle 的退款文档。

exclamation

退款必须始终在完全处理之前获得 Paddle 的批准。

贷记交易

与退款一样，您也可以对交易进行信用。信用交易会将资金添加到客户的余额中，以便用于未来的购买。信用交易只能针对手动收集的交易进行，而不能针对自动收集的交易（如订阅），因为 Paddle 会自动处理订阅信用。

$transaction = $user->transactions()->first();
 
// Credit a specific line item fully...
$response = $transaction->credit('Compensation', 'pri_123');

有关更多信息，请参阅 Paddle 关于信用的文档。

exclamation

信用只能应用于手动收集的交易。自动收集的交易由 Paddle 本身进行信用。

交易

您可以通过 transactions 属性轻松检索可计费模型的交易数组。

use App\Models\User;
 
$user = User::find(1);
 
$transactions = $user->transactions;

交易代表您的产品和购买的付款，并附有发票。只有完成的交易才会存储在您的应用程序数据库中。

在列出客户的交易时，您可以使用交易实例的方法来显示相关的付款信息。例如，您可能希望在表格中列出每笔交易，从而允许用户轻松下载任何发票。

<table>
    @foreach ($transactions as $transaction)
        <tr>
            <td>{{ $transaction->billed_at->toFormattedDateString() }}</td>
            <td>{{ $transaction->total() }}</td>
            <td>{{ $transaction->tax() }}</td>
            <td><a href="{{ route('download-invoice', $transaction->id) }}" target="_blank">Download</a></td>
        </tr>
    @endforeach
</table>

download-invoice 路由可能如下所示：

use Illuminate\Http\Request;
use Laravel\Paddle\Transaction;
 
Route::get('/download-invoice/{transaction}', function (Request $request, Transaction $transaction) {
    return $transaction->redirectToInvoicePdf();
})->name('download-invoice');

过去和即将到来的付款

您可以使用 lastPayment 和 nextPayment 方法来检索和显示客户的过去或即将到来的定期订阅付款。

use App\Models\User;
 
$user = User::find(1);
 
$subscription = $user->subscription();
 
$lastPayment = $subscription->lastPayment();
$nextPayment = $subscription->nextPayment();

这两个方法都将返回 Laravel\Paddle\Payment 的实例；但是，当 Webhook 尚未同步交易时，lastPayment 将返回 null，而当结算周期结束时（例如，当订阅已取消时），nextPayment 将返回 null。

Next payment: {{ $nextPayment->amount() }} due on {{ $nextPayment->date()->format('d/m/Y') }}

测试

在测试时，您应手动测试您的账单流程，以确保您的集成按预期工作。

对于自动化测试，包括在 CI 环境中执行的测试，您可以使用 Laravel 的 HTTP 客户端来伪造对 Paddle 发出的 HTTP 调用。尽管这不会测试来自 Paddle 的实际响应，但它确实提供了一种在不实际调用 Paddle API 的情况下测试应用程序的方法。