Laravel Cashier

介紹

Laravel Cashier 提供語義化，流暢的接口和 Stripe 的訂購管理服務(wù)集成。它幾乎處理了所有讓人退步三舍的訂購管理相關(guān)邏輯。除了基本的訂購管理，Cashier 還可以處理折價(jià)券，訂購轉(zhuǎn)換，管理訂購「數(shù)量」、服務(wù)有效期限，甚至產(chǎn)生收據(jù)的 PDF。

配置文件

Composer

首先，把 Cashier 擴(kuò)展包加到 composer.json：

"laravel/cashier": "~5.0" (For Stripe SDK ~2.0, and Stripe APIs on 2015-02-18 version and later)"laravel/cashier": "~4.0" (For Stripe APIs on 2015-02-18 version and later)"laravel/cashier": "~3.0" (For Stripe APIs up to and including 2015-02-16 version)

注冊服務(wù)

然后，在 app 配置文件注冊 Laravel\Cashier\CashierServiceProvider。

遷移

使用 Cashier 前，我們需要增加幾個(gè)字段到數(shù)據(jù)庫。別擔(dān)心，你可以使用 cashier:table Artisan 命令，建立遷移文件來添加必要字段。例如，要增加字段到 users 數(shù)據(jù)表，使用 php artisan cashier:table users。建立完遷移文件后，只要執(zhí)行 migrate 命令即可。

配置模型

然后，把 Billable trait 和相關(guān)的日期字段參數(shù)加到模型里：

use Laravel\Cashier\Billable;use Laravel\Cashier\Contracts\Billable as BillableContract;class User extends Model implements BillableContract {

    use Billable;

    protected $dates = ['trial_ends_at', 'subscription_ends_at'];}

Stripe Key

最后, 在 services.php 配置文件中設(shè)置你的 Stripe key：

'stripe' => [
    'model'  => 'User',
    'secret' => env('STRIPE_API_SECRET'),],

或者，也可以在初始化文件 (bootstrap) 或服務(wù)提供者中（如 AppServiceProvider ）加入 Stripe key：

User::setStripeKey('stripe-key');

訂購方案

當(dāng)有了模型實(shí)例，你可以很簡單的處理客戶訂購的 Stripe 里的方案：

$user = User::find(1);$user->subscription('monthly')->create($creditCardToken);

如果你想在建立訂購的時(shí)候使用折價(jià)券，可以使用 withCoupon 方法：

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

subscription 方法會自動建立與 Stripe 的交易，以及將 Stripe customer ID 和其他相關(guān)帳款信息更新到數(shù)據(jù)庫。如果你的方案有在 Stripe 配置試用期，試用到日期也會自動記錄起來。

如果你的方案有試用期間，但是沒有在 Stripe 里配置，你必須在處理訂購后手動保存試用到日期。

$user->trial_ends_at = Carbon::now()->addDays(14);$user->save();

自定義額外用戶詳細(xì)數(shù)據(jù)

如果你想自定義額外的顧客詳細(xì)數(shù)據(jù)，你可以將數(shù)據(jù)數(shù)組作為 create 方法的第二個(gè)參數(shù)傳入：

$user->subscription('monthly')->create($creditCardToken, [
    'email' => $email, 'description' => 'Our First Customer']);

想知道更多 Stripe 支持的額外字段，可以查看 Stripe 的在線文檔 建立客戶。

一次性付款

如果你想使用一次性付款而不是信用卡訂購方案，你可以使用 charge 方法：

$user->charge(100);

charge 方法接受一個(gè)用最低單位貨幣的數(shù)量參數(shù)。 比如，上面的例子中會付款 100 美分 或者 1.00 美元，而不是用戶的信用卡。

charge 方法也接受一個(gè)數(shù)組作為第二個(gè)參數(shù)，允許你傳入一些創(chuàng)建 Stripe 訂購的選項(xiàng)：

$user->charge(100, [
    'source' => $token,
    'receipt_email' => $user->email,]);

如果付款失敗，charge 方法會返回 false。一般來說，這意味著付款被拒絕：

if ( ! $user->charge(100)){
    // The charge was denied...}

如果付款成功, 一個(gè)完整的 Stripe 響應(yīng)會從這個(gè)方法返回。

免信用卡試用

如果你提供免信用卡試用服務(wù)，把 cardUpFront 屬性設(shè)為 false：

protected $cardUpFront = false;

建立帳號時(shí)，記得把試用到日期記錄起來：

$user->trial_ends_at = Carbon::now()->addDays(14);$user->save();

訂購轉(zhuǎn)換

使用 swap 方法可以把用戶轉(zhuǎn)換到新的訂購：

$user->subscription('premium')->swap();

如果用戶還在試用期間，試用服務(wù)會跟之前一樣可用。如果訂單有「數(shù)量」，也會和之前一樣。

訂購數(shù)量

有時(shí)候訂購行為會跟「數(shù)量」有關(guān)。例如，你的應(yīng)用程序可能會依照帳號的用戶人數(shù)，每人每月收取 $10 元。你可以使用 increment 和 decrement 方法簡單的調(diào)整訂購數(shù)量：

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

Subscription Tax

With Cashier, it's easy to override the tax_percent value sent to Stripe. To specify the tax percentage a user pays on a subscription, implement the getTaxPercent method on your model, and return a numeric value between                0 and 100, with no more than 2 decimal places.

public function getTaxPercent(){
    return 20;}

This enables you to apply a tax rate on a model-by-model basis, which may be helpful for a user base that spans multiple countries.

取消訂購

取消訂購相當(dāng)簡單：

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

當(dāng)客戶取消訂購時(shí)，Cashier 會自動更新數(shù)據(jù)庫的 subscription_ends_at 字段。這個(gè)字段會被用來判斷 subscribed 方法是否該返回 false。例如，如果顧客在三月一號取消訂購，但是服務(wù)可以使用到三月五號為止，那么 subscribed 方法在三月五號前都會傳回 true。

恢復(fù)訂購

如果你想要恢復(fù)客戶之前取消的訂購，使用 resume 方法：

$user->subscription('monthly')->resume($creditCardToken);

如果客戶取消訂購后，在服務(wù)過期前恢復(fù)，他們不用在當(dāng)下付款。他們的服務(wù)會立刻重啟，而付款則會遵循平常的流程。

確認(rèn)訂購狀態(tài)

要確認(rèn)用戶是否訂購了你的應(yīng)用，使用 subscribed 方法：

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

subscribed 方法很適合用在 路由中間件:

public function handle($request, Closure $next){
    if ($request->user() && ! $request->user()->subscribed())
    {
        return redirect('billing');
    }

    return $next($request);}

你可以使用 onTrial 方法，確認(rèn)用戶是否還在試用期間：

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

要確認(rèn)用戶是否曾經(jīng)訂購但是已經(jīng)取消了服務(wù)，可以使用 cancelled 方法：

if ($user->cancelled()){
    //}

你可能想確認(rèn)用戶是否已經(jīng)取消訂單，但是服務(wù)還沒有到期。例如，如果用戶在三月五號取消了訂購，但是服務(wù)會到三月十號才過期。那么用戶到三月十號前都是有效期間。注意， subscribed 方法在過期前都會返回 true 。

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

everSubscribed 方法可以用來確認(rèn)用戶是否訂購過應(yīng)用程序里的方案：

if ($user->everSubscribed()){
    //}

onPlan 方法可以用方案 ID 來確認(rèn)用戶是否訂購某方案：

if ($user->onPlan('monthly')){
    //}

處理失敗訂閱

如果顧客的信用卡過期了呢？無需擔(dān)心，Cashier 包含了 Webhook 控制器，可以幫你簡單的取消顧客的訂單。只要在路由注冊控制器：

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

這樣就成了！失敗的交易會經(jīng)由控制器捕捉并進(jìn)行處理?？刂破鲿M(jìn)行至多三次再交易嘗試，當(dāng) Stripe 認(rèn)為三次都失敗后才會取消顧客的訂單。上面的 stripe/webhook URI 只是一個(gè)例子，你必須使用配置在 Stripe 里的 URI 才行。

處理其它 Stripe Webhooks

如果你想要處理額外的 Stripe webhook 事件，可以繼承 Webhook 控制器。你的方法名稱要對應(yīng)到 Cashier 預(yù)期的名稱，尤其是方法名稱應(yīng)該使用 handle 前綴，后面接著你想要處理的 Stripe webhook 。例如，如果你想要處理 invoice.payment_succeeded webhook ，你應(yīng)該增加一個(gè) handleInvoicePaymentSucceeded                方法到控制器。

class WebhookController extends Laravel\Cashier\WebhookController {

    public function handleInvoicePaymentSucceeded($payload)
    {
        // Handle The Event    }}

注意： 除了更新你數(shù)據(jù)庫里的訂購信息以外， Webhook 控制器也會經(jīng)由 Stripe API 取消你的訂購。

收據(jù)

你可以很簡單的經(jīng)由 invoices 方法拿到客戶的收據(jù)數(shù)據(jù)數(shù)組：

$invoices = $user->invoices();

你可以使用這些輔助方法，列出收據(jù)的相關(guān)信息給客戶看：

{{ $invoice->id }}{{ $invoice->dateString() }}{{ $invoice->dollars() }}

使用 downloadInvoice 方法產(chǎn)生收據(jù)的 PDF 下載。是的，它非常容易：

return $user->downloadInvoice($invoice->id, [
    'vendor'  => 'Your Company',
    'product' => 'Your Product',]);