Laravel Cashier

介紹

Laravel Cashier 提供口語化,流暢的介面和 Stripe 的訂購管理服務介接。它幾乎處理了所有讓人退步三舍的訂購管理相關邏輯。除了基本的訂購管理,Cashier 還可以處理折價券,訂購轉換,管理訂購「數量」、服務有效期限,甚至產生收據的 PDF。

設定檔

Composer

首先,把 Cashier 套件加到 composer.json

"laravel/cashier": "~2.0"

服務提供者

再來,在 app 設定檔註冊 Laravel\Cashier\CashierServiceProvider

遷移

使用 Cashier 前,我們需要增加幾個欄位到資料庫。別擔心,你可以使用 cashier:table Artisan 命令,建立遷移檔來新增必要欄位。例如,要增加欄位到 users 資料表,使用 php artisan cashier:table users。建立完遷移檔後,只要執行 migrate 命令即可。

設定模型

再來,把 BillableTrait 和日期欄位參數加到模型裡:

use Laravel\Cashier\BillableTrait;
use Laravel\Cashier\BillableInterface;

class User extends Eloquent implements BillableInterface {

    use BillableTrait;

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

}

Stripe Key

最後,在起始檔裡加入 Stripe key:

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

訂購方案

當有了模型實例,你可以很簡單的處理客戶訂購的 Stripe 裡的方案:

$user = User::find(1);

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

如果你想在處理訂購的時候使用折價券,可以使用 withCoupon 方法:

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

subscription 方法會自動建立與 Stripe 的交易,以及將 Stripe customer ID 和其他相關帳款資訊更新到資料庫。如果你的方案有在 Stripe 設定試用期,試用到期日也會自動記錄起來。

如果你的方案有試用期間,但是沒有在 Stripe 裡設定,你必須在訂購後手動儲存試用到期日。

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

$user->save();

自定額外使用者詳細資料

如果你想自定額外的顧客詳細資料,你可以將資料陣列作為 create 方法的第二個參數傳入:

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

想知道更多 Stripe 支援的額外欄位,瞧瞧 Stripe 的線上文件 建立客戶

免信用卡試用

如果你提供免信用卡試用服務,把 cardUpFront 屬性設為 false

protected $cardUpFront = false;

建立帳號時,記得把試用到期日記錄起來:

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

$user->save();

訂購轉換

使用 swap 方法可以把使用者轉換到新的訂購:

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

如果使用者還在試用期間,試用服務會跟之前一樣可用。如果訂單有「數量」,也會和之前一樣。

訂購數量

有時候訂購行為會跟「數量」有關。例如,你的應用程式可能會跟使用者每個月收取 $10 元。你可以使用 incrementdecrement 方法簡單的調整訂購數量:

$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);

取消訂購

取消訂購相當簡單:

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

當客戶取消訂購時,Cashier 會自動更新資料庫的 subscription_ends_at 欄位。這個欄位會被用來判斷 subscribed 方法是否該回傳 false。例如,如果顧客在三月一號取消訂購,但是服務可以使用到三月五號為止,那麼 subscribed 方法在三月五號前都會傳回 true

恢復訂購

如果你想要恢復客戶之前取消的訂購,使用 resume 方法:

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

如果客戶取消訂購後,在服務過期前恢復,他們不用在當下付款。他們的服務會立刻重啟,而付款則會循平常的流程。

確認訂購狀態

要確認使用者是否訂購了服務,使用 subscribed 方法:

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

subscribed 方法很適合用在路由過濾:

Route::filter('subscribed', function()
{
    if (Auth::user() && ! Auth::user()->subscribed())
    {
        return Redirect::to('billing');
    }
});

你可以使用 onTrial 方法,確認使用者是否還在試用期間:

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

要確認使用者是否曾經訂購但是已經取消了服務,可已使用 cancelled 方法:

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

你可以可能想確認使用者是否已經取消訂單,但是服務還沒有到期。例如,如果使用者在三月五號取消了訂購,但是服務會到三月十號才過期。那麼使用者到三月十號前都是有效期間。注意, subscribed 方法在過期前都會回傳 true

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

everSubscribed 方法可以用來確認使用者是否訂購過你的方案:

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

onPlan 方法可以用方案 ID 來確認使用者是否訂購某方案:

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

處理交易失敗

如果顧客的信用卡過期了呢?無需擔心,Cashier 包含了 Webhook 控制器,可以幫你簡單的取消顧客的訂單。只要把路由註冊到控制器:

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

這樣就成了!失敗的交易會經由控制器捕捉並進行處理。控制器會進行至多三次再交易嘗試,都失敗後才會取消顧客的訂單。上面的 stripe/webhook URI 只是一個範例,你必須使用設定在 Stripe 裡的 URI 才行。

處理其它 Stripe Webhooks

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

class WebhookController extends Laravel\Cashier\WebhookController {

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

}

注意: 除了更新你資料庫裡的訂購資訊以外, Webhook 控制器也可能會經由 Stripe API 取消你的訂購。

收據

你可以很簡單的經由 invoices 方法拿到客戶的收據資料陣列:

$invoices = $user->invoices();

你可以使用這些輔助方法,列出收據的相關資訊給客戶看:

{{ $invoice->id }}

{{ $invoice->dateString() }}

{{ $invoice->dollars() }}

使用 downloadInvoice 方法產生收據的 PDF 下載。是的,它非常容易:

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