版本：5.2

Laravel Cashier

简介

Laravel Cashier 给 Stripe 和 Braintree's 的订购交易服务提供了生动流畅的接口。它基本上处理了所有会让人恐惧的订购管理的相关逻辑。除了基本的订购管理外，Cashier 还可以处理优惠券，订购转换，管理订购「数量」、取消宽限期，甚至生成发票的 PDF 文件。

Stripe 配置

Composer

首先，将 Cashier 扩展包添加至 composer.json 文件并运行 composer update 命令：

"laravel/cashier": "~6.0"

译者注：请使用 require 来安装扩展包，讨论请见正确的 Composer 扩展包安装方法

服务提供者

接着，在 app 配置文件中注册 Laravel\Cashier\CashierServiceProvider 服务提供者。

数据库迁移

我们需要添加新字段到 users 用户表中，并且创建 subscriptions 表用来存放所有用户的订阅信息：

Schema::table('users', function ($table) {
    $table->string('stripe_id')->nullable();
    $table->string('card_brand')->nullable();
    $table->string('card_last_four')->nullable();
    $table->timestamp('trial_ends_at')->nullable();
});

Schema::create('subscriptions', function ($table) {
    $table->increments('id');
    $table->integer('user_id');
    $table->string('name');
    $table->string('stripe_id');
    $table->string('stripe_plan');
    $table->integer('quantity');
    $table->timestamp('trial_ends_at')->nullable();
    $table->timestamp('ends_at')->nullable();
    $table->timestamps();
});

在数据库迁移文件创建完毕后请运行 migrate Artisan 命令。

模型设置

接着，将 Billable trait 和适当的日期访问器添加至你的模型定义中：

use Laravel\Cashier\Billable;

class User extends Authenticatable
{
    use Billable;
}

Stripe 密钥

最后，在你的 services.php 配置文件中设置 Stripe 密钥：

'stripe' => [
    'model'  => App\User::class,
    'secret' => env('STRIPE_SECRET'),
],

Braintree 配置

Braintree 警告

对于大部分的操作，Stripe 和 Braintree 的功能基本上一样。两个服务都支持行用卡支付，不过 Braintree 支持 PayPal。Braintree 也缺少一些 Stripe 的功能，在你选择的时候可以参考一下：

Braintree 支持 PayPal，Stripe 不支持。
Braintree 不支持订阅的 increment 和 decrement 方法。这是 Braintree 的接口限制，不是 Cashier 的。
Braintree 不支持按照百分比的折扣。这是 Braintree 的接口限制，不是 Cashier 的。

Composer

首先，将 Cashier 扩展包添加至 composer.json 文件并运行 composer update 命令：

"laravel/cashier-braintree": "~1.0"

服务提供者

接着，在 app 配置文件中注册 Laravel\Cashier\CashierServiceProvider 服务提供者。

计划积分优惠券

在使用 Cashier 中使用 Braintree 之前，你需要在 Braintree 的控制台上定义一个 plan-credit 优惠计划。这个计划会用来合理分配从月度订阅升级到年度订阅的改变，或者年度订阅降级到月度订阅的改变。在 Braintree 的控制台中，你可以为这个计划任意设置一个值，Cashier 会在每一次变更优惠券的时候覆盖此值。

数据库迁移

我们需要添加新字段到 users 用户表中，并且创建 subscriptions 表用来存放所有用户的订阅信息：

Schema::table('users', function ($table) {
    $table->string('braintree_id')->nullable();
    $table->string('paypal_email')->nullable();
    $table->string('card_brand')->nullable();
    $table->string('card_last_four')->nullable();
    $table->timestamp('trial_ends_at')->nullable();
});

Schema::create('subscriptions', function ($table) {
    $table->increments('id');
    $table->integer('user_id');
    $table->string('name');
    $table->string('braintree_id');
    $table->string('braintree_plan');
    $table->integer('quantity');
    $table->timestamp('trial_ends_at')->nullable();
    $table->timestamp('ends_at')->nullable();
    $table->timestamps();
});

在数据库迁移文件创建完毕后请运行 migrate Artisan 命令。

模型设置

接着，将 Billable trait 和适当的日期访问器添加至你的模型定义中：

use Laravel\Cashier\Billable;

class User extends Authenticatable
{
    use Billable;
}

秘钥设置

在你的 services.php 配置文件中设置 Stripe 密钥：

'braintree' => [
    'model'  => App\User::class,
    'environment' => env('BRAINTREE_ENV'),
    'merchant_id' => env('BRAINTREE_MERCHANT_ID'),
    'public_key' => env('BRAINTREE_PUBLIC_KEY'),
    'private_key' => env('BRAINTREE_PRIVATE_KEY'),
],

然后你还需要增加这些 SDK 调用到你的 AppServiceProvider 服务提供者的 boot 方法内：

\Braintree_Configuration::environment(env('BRAINTREE_ENV'));
\Braintree_Configuration::merchantId(env('BRAINTREE_MERCHANT_ID'));
\Braintree_Configuration::publicKey(env('BRAINTREE_PUBLIC_KEY'));
\Braintree_Configuration::privateKey(env('BRAINTREE_PRIVATE_KEY'));

订购

创建订购

要创建一个订购，首先要获取可交易的模型实例，这通常会是 App\User 的实例。一旦你获取了模型实例，你可以使用 subscription 方法来管理模型的订购：

$user = User::find(1);

$user->newSubscription('main', 'monthly')->create($creditCardToken);

newSubscription 方法的第一个参数是订阅的名称，如果你的应用程序只提供一种订阅的话，可以考虑把这个方案命名为 main 或者 primary。第二个参数是用户订阅的 Stripe / Braintree 计划。这个值应该对应 Stripe 和 Braintree 的后台唯一标识符。

create 方法会自动创建订阅并且更新客户 ID 和账单相关的信息。

额外用户详细数据

如果你想自定义额外的顾客详细数据，可以将数据数组作为 create 方法的第二个参数传入：

$user->subscription('monthly')->create($creditCardToken, [
    'email' => $email, 'description' => '我们的第一个客户'
]);

想知道更多 Stripe 支持的额外字段，请查看 Stripe 的创建顾客文档。

优惠券

如果你想在创建订购的时候使用优惠券，可以使用 withCoupon 方法：

$user->subscription('monthly')
     ->withCoupon('code')
     ->create($creditCardToken);

确认订购状态

一旦用户在你的应用程序完成订购，你便可以使用多种方法来检查他们的订购状态。首先，当用户拥有有效订购时，subscribed 方法会返回 true，即使该订购目前在试用期间：

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

subscribed 方法很适合用在路由中间件，让你可以通过用户的订购状态，过滤访问路由及控制器：

public function handle($request, Closure $next)
{
    if ($request->user() && ! $request->user()->subscribed('main')) {
        // This user is not a paying customer...
        return redirect('billing');
    }

    return $next($request);
}

如果你想确认用户是否还在他们的试用期内，你可以使用 onTrial 方法。利用此方法可以在页面的顶部展示正在试用期内的提示：

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

subscribedToPlan 方法允许你使用 Stripe ID / Braintree 计划 ID 来确认用户是否订购某方案。在这个列子中，我们检查用户的 main 订阅是否有 monthly计划：

if ($user->subscribedToPlan('monthly', 'main')) {
    //
}

取消订购状态

若要确认用户是否曾经订购过，但现在已取消订购，你可以使用 cancelled 方法：

if ($user->subscription('main')->cancelled()) {
    //
}

你可能想确认用户是否已经取消订购，但是订购还在他们完全到期前的「宽限期」内。例如，如果用户在三月五号取消了订购，但是服务会到三月十号才过期。那么用户到三月十号前都是「宽限期」。注意，subscribed 方法在这个期间仍然会返回 true。

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

改变方案

当用户在你的应用程序订购之后，他们有时可能想更改自己的订购方案。使用 swap 方法可以把用户转换到新的订购方案。举个例子，我们可以简单的将用户切换至 premium 订购方案：

$user = App\User::find(1);

$user->subscription('main')->swap('provider-plan-id');

如果用户是在试用阶段的话，用户的试用计划会被继续保持。如果订阅有订购数量存在的话，订购数量也会被保持。

$user->subscription('main')->swap('provider-plan-id');

如果你想切换到一个订阅计划，但是跳过「试用」的话，可以使用 skipTrial 方法来实现： $user->subscription('main') ->skipTrial() ->swap('provider-plan-id');

订购数量

注意

订购数量只有 Stripe 支持。

有时候订购行为会跟「数量」有关。例如，你的应用程序可能会依照帐号的用户人数，每人每月收取 10 元。你可以使用 incrementQuantity 和 decrementQuantity 方法简单的调整订购数量：

$user = User::find(1);

$user->subscription('main')->incrementQuantity();

// 增加 5 个订购数量...
$user->subscription('main')->incrementQuantity(5);

$user->subscription('main')->decrementQuantity();

// 减少 5 个订购数量...
$user->subscription('main')->decrementQuantity(5);

另外，你也可以使用 updateQuantity 方法来设置指定的数量：

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

有关订购数量的更多数据，请参阅 Stripe 文档。

订购税金

在 Cashier 中，可以很容易的提供发送至 Stripe 的 tax_percent 值。要指定一个用户付费订购时的税金比例，请在你的交易模型中实现 getTaxPercent 方法，并返回一个介于 0 至 100 间，且不超过两位小数的数值。

public function getTaxPercent() {
    return 20;
}

这能让你基于个别模型去运用税率，可能对横跨多个国家的用户群非常有帮助。

取消订购

要取消一个订购，只需要在用户的订购调用 cancel 方法：

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

当订购被取消时，Cashier 会自动更新数据库的 ends_at 字段。这个字段会被用来判断 subscribed 方法什么时候该开始返回 false。例如，如果顾客在三月一号取消订购，但是服务可以使用到三月五号为止，那么 subscribed 方法在三月五号前都会传回 true。

你想确认用户是否已经取消他们的订购，但是还在他们的「宽限期」内，可以使用 onGracePeriod 方法：

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

恢复订购

如果用户已经取消了他们的订购，但你想恢复订购，可以使用 resume 方法。用户必须仍处在宽限期内：

$user->subscription('main')->resume();

如果客户取消订购后，且接着在服务完全过期前恢复订购，他们将不会在当下被扣款。他们的订购会被重新启动，而付款则会依照平常的周期。

订购试用

预先绑定信用卡

你可以使用 trialDays 为你的客户提供一定时间的试用期限方案：

$user = User::find(1);

$user->newSubscription('main', 'monthly')
            ->trialDays(10)
            ->create($creditCardToken);

此方法会更新数据库中的订阅记录的试用终止时间，同时会指示 Stripe / Braintree 在这个终止时间之前不做计费处理。

注意

你应该在试用期快终止的时候通知你的用户，因为试用期一到，订阅服务将开始计费。

你可以在用户实例或者用户的订阅实例上使用 onTrial 方法来判断当前用户是否正处于试用期内：

if ($user->onTrial('main')) {
    //
}

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

不需要预先绑定信用卡

如果你不要求用户在开始试用期的时候绑定信用卡，你可以直接更新用户表里的 trial_ends_at 字段。一般的操作是在注册用户的时候设置 trial_ends_at 试用期过期时间：

$user = User::create([
    // Populate other user properties...
    'trial_ends_at' => Carbon::now()->addDays(10),
]);

因为这种试用类型不需要绑定订阅，Cashier 称呼这种类型的试用为「通用试用（generic trial）」。如果 trial_ends_at 这个时间还没过期的话，User 实例上的 onTrial 会返回 true：

if ($user->onTrial()) {
    // 用户是否还在试用期
}

你可以使用 onGenericTrial 来判断某个用户是否还在试用期内，并且使用的是「通用试用」类型：

if ($user->onGenericTrial()) {
    // 用户是否还在 「通用试用」类型试用期限内
}

当用户准备好要订阅的时候，你可以使用 newSubscription 方法：

$user = User::find(1);

$user->newSubscription('main', 'monthly')->create($creditCardToken);

处理 Stripe Webhooks

订购失败

如果顾客的信用卡过期了呢？无需担心，Cashier 包含了 Webhook 控制器，可以帮你简单的取消顾客的订单。只要在路由注册控制器：

Route::post(
    'stripe/webhook',
    '\Laravel\Cashier\Http\Controllers\WebhookController@handleWebhook'
);

这样就完成了！失败的交易会经由控制器捕捉并进行处理。控制器在 Stripe 确认订购已经失败后 (通常在三次交易尝试失败后)，才会取消顾客的订单。别忘了：你必须设置 Stripe 控制设置里的 webhook URI。

由于 Stripe Webhooks 必须绕过 Laravel 的 CSRF 验证，请确定在增加 URI 异常至你的 VerifyCsrfToken 中间件，或者在把路由设置于 web 路由组外：

protected $except = [
    'stripe/*',
];

其它 Webhooks

如果你想要处理额外的 Stripe Webhook 事件，只需要继承 Webhook 控制器。你的方法名称要对应到 Cashier 默认的名称，尤其是方法名称应该使用 handle 前缀，并使用「驼峰式」命名法，后面接着你想要处理的 Stripe webhook。例如，如果你想要处理 invoice.payment_succeeded webhook，你应该增加一个 handleInvoicePaymentSucceeded 方法到控制器。

<?php

namespace App\Http\Controllers;

use Laravel\Cashier\Http\Controllers\WebhookController as BaseController;

class WebhookController extends BaseController
{
    /**
     * 处理一个 stripe webhook。
     *
     * @param  array  $payload
     * @return Response
     */
    public function handleInvoicePaymentSucceeded($payload)
    {
        // 处理该事件
    }
}

处理 Braintree Webhooks

订购失败

如果顾客的信用卡过期了呢？无需担心，Cashier 包含了 Webhook 控制器，可以帮你简单的取消顾客的订单。只要在路由注册控制器：

Route::post(
    'braintree/webhook',
    '\Laravel\Cashier\Http\Controllers\WebhookController@handleWebhook'
);

这样就完成了！失败的交易会经由控制器捕捉并进行处理。控制器在 Braintree 确认订购已经失败后 (通常在三次交易尝试失败后)，才会取消顾客的订单。别忘了：你必须设置 Stripe 控制设置里的 webhook URI。

由于 Braintree Webhooks 必须绕过 Laravel 的 CSRF 验证，请确定在增加 URI 异常至你的 VerifyCsrfToken 中间件，或者在把路由设置于 web 路由组外：

protected $except = [
    'braintree/*',
];

其他的 Webhooks

如果你需要处理其他的 Braintree Webhook 事件，你可以直接扩展 Webhook 控制器。方法的命名规范是依照 Webhook 来命名的，在 Webhook 前面增加前缀，然后使用驼峰命名法。如：dispute_opened 接口，对应的方法名为 handleDisputeOpened：

<?php

namespace App\Http\Controllers;

use Braintree\WebhookNotification;
use Laravel\Cashier\Http\Controllers\WebhookController as BaseController;

class WebhookController extends BaseController
{
    /**
     * 处理一个 Braintree webhook
     *
     * @param  WebhookNotification  $webhook
     * @return Response
     */
    public function handleDisputeOpened(WebhookNotification $notification)
    {
        // 处理事件的逻辑
    }
}

一次性收费

简单收费

注意

当你使用 Stripe 的时候，charge 会接受当前应用使用的货币最小分母，而 Braintree 使用的是完整的美元单位。

如果你想对一个已订购客户的信用卡进行「一次性」收费，你可以对一个交易模型实例使用 charge 方法。charge 方法接受你想收取 应用程序使用货币的最低单位 的金额。所以，举例来说，下方的例子将会对用户的信用卡收取 100 美分，或是 1 美元：

// Stripe 收取的是以美分为单位
$user->charge(100);

// Braintree 收取的是以美元为单位
$user->charge(1);

charge 方法接受一个数组作为第二个参数，你可以传递任何你希望的选项至底层的 Stripe 付费创建器：

$user->charge(100, [
    'custom_option' => $value,
]);

当收费失败时 charge 方法会抛出异常。完整的 Stripe / Braintree response 响应会被返回：

try {
    $response = $user->charge(100);
} catch (Exception $e) {
    //
}

收费并生成发票

你可以使用 invoiceFor 来一次性收费并生成发票，例如 一次性收费 是 $5.00。

// Stripe 收取的是以美分为单位
$user->invoiceFor('One Time Fee', 500);

// Braintree 收取的是以美元为单位
$user->invoiceFor('One Time Fee', 5);

此次对用户的信用卡收费会在即刻发生。方法 invoiceFor 还可以接受第三个参数，此参数以数字形式出现，你可以使用此参数在收费创建时給 Stripe / Braintree 传送信息：

$user->invoiceFor('One Time Fee', 500, [
    'custom-option' => $value,
]);

发票

你可以很简单的通过 invoices 方法获取交易模型的发票数据数组：

$invoices = $user->invoices();

当列出发票给客户时，你可以使用发票的辅助函数来显示发票的相关信息。举例来说，你可能希望在表格中列出每个发票的信息，让用户可以简单对其中一个进行下载：

<table>
    @foreach ($invoices as $invoice)
        <tr>
            <td>{{ $invoice->date()->toFormattedDateString() }}</td>
            <td>{{ $invoice->total() }}</td>
            <td><a href="/user/invoice/{{ $invoice->id }}">Download</a></td>
        </tr>
    @endforeach
</table>

生成发票的 PDF

在生成 PDF 的时候，你需要安装 dompdf 扩展包：

composer require dompdf/dompdf

在路由或是控制器中，使用 downloadInvoice 方法可以触发发票的 PDF 下载动作，此方法会自动生成正确的 HTTP 响应并发送下载动作至浏览器：

Route::get('user/invoice/{invoice}', function ($invoiceId) {
    return Auth::user()->downloadInvoice($invoiceId, [
        'vendor'  => 'Your Company',
        'product' => 'Your Product',
    ]);
});

备注

欢迎任何形式的转载，但请务必注明出处，尊重他人劳动共创开源社区。

转载请注明：本文档由 Laravel China 社区 [laravel-china.org] 组织翻译。

文档永久地址： http://d.laravel-china.org

简介​

Stripe 配置​

Composer​

服务提供者​

数据库迁移​

模型设置​

Stripe 密钥​

Braintree 配置​

Braintree 警告​

Composer​

服务提供者​

计划积分优惠券​

数据库迁移​

模型设置​

秘钥设置​

订购​

创建订购​

额外用户详细数据​

优惠券​

确认订购状态​

取消订购状态​

改变方案​

订购数量​

订购税金​

取消订购​

恢复订购​

订购试用​

预先绑定信用卡​

不需要预先绑定信用卡​

处理 Stripe Webhooks​

订购失败​

其它 Webhooks​

处理 Braintree Webhooks​

订购失败​

其他的 Webhooks​

一次性收费​

简单收费​

收费并生成发票​

发票​

生成发票的 PDF​

简介

Stripe 配置

Composer

服务提供者

数据库迁移

模型设置

Stripe 密钥

Braintree 配置

Braintree 警告

Composer

服务提供者

计划积分优惠券

数据库迁移

模型设置

秘钥设置

订购

创建订购

额外用户详细数据

优惠券

确认订购状态

取消订购状态

改变方案

订购数量

订购税金

取消订购

恢复订购

订购试用

预先绑定信用卡

不需要预先绑定信用卡

处理 Stripe Webhooks

订购失败

其它 Webhooks

处理 Braintree Webhooks

订购失败

其他的 Webhooks

一次性收费

简单收费

收费并生成发票

发票

生成发票的 PDF