Laravelキャッシャー 4.2 Laravel

イントロダクション

Laravelキャッシャーは、Stripeによる購読（定期課金）サービスの、読みやすく、スラスラと記述できるインターフェイスを提供します。これにより、書くことが恐ろしくなるような、購読支払いのための決まりきったコードのほとんどが処理できます。基本的な購読管理に加え、キャッシャーはクーポン、購読の変更、購入数、キャンセル猶予期間、さらにインボイスのPDF発行まで行います。

設定

Composer

最初に、composer.jsonファイルに、Cashierパッケージを追加します。

"laravel/cashier": "~2.0"

サービスプロバイダー

次に、app設定ファイルへ、Laravel\Cashier\CashierServiceProviderを登録します。

マイグレーション

キャッシャーを使用する前に、データベースにいくつかカラムを追加する必要があります。心配ありません。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キー

最後に、初期設定ファイルのどれかで、Stripeキーを指定します。

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のカスタマー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がサポートしている追加のフィールドについては、顧客の作成に関するドキュメントをご覧ください。

カードの前払いなし

アプリケーションで、カードによる前払いなしの試用期間を提供する場合、モデルのcardUpFrontプロパティーをfalseに設定してください。

protected $cardUpFront = false;

アカウント作成時に、試用期間の最終日をモデルへセットするのをお忘れなく。

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

$user->save();

購読の変更

ユーザーの購読を新しいものへ変更する場合、swapメソッドを使用してください。

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

ユーザーが試用期間中の場合、試用期間は通常通りに続きます。また、その購読に"quantity"（購読数）が存在する場合、その個数も維持されます。

購読数

時々、購読数により、購読が影響を受けることがあります。例えば、あなたのアプリケーションで、一つのアカウントごとに一月１０ドル課金しているとしましょう。incrementとdecrementメソッドで、簡単に購読数を増減できます。

$user = User::find(1);

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

// 現在の購読数に５つ加える…
$user->subscription()->increment(5);

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

// 現在の購読数から５つ減らす…
$user->subscription()->decrement(5);

購読のキャンセル

購読のキャンセルも、お茶の子さいさいです。

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

購読がキャンセルされると、キャッシャーは自動的に、データベースの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メソッドは、この期間中、まだtureを返すことに注目して下さい。

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

everSubscribedメソッドにより、そのユーザーがアプリケーションの、永久購読プランを持っているかを決定することができます。

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

onPlanメソッドにより、そのユーザーが指定されたIDのプランを購入しているかを判定できます。

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

支払不能時の処理

顧客のクレジットカードが、有効期限切れだったら？キャッシャーは、顧客の購読を簡単にキャンセルする、Webフックコントローラーを用意しています。コントローラーへのルートを指定するだけです。

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

これだけです！課金の失敗は、コントローラーにより捉えられ、処理されます。コントローラーは課金に３回失敗すると、その顧客の購読をキャンセルします。この場合のURI、stripe/webhookはただの例にすぎません。Stripe設定のURIを設定する必要があります。

他のStripe Webフックの処理

処理したい追加のStripe Webフックイベントがある場合、シンプルにWebフックコントローラーを拡張してください。メソッド名はCashierが期待する命名規則に従う必要があります。つまり、メソッド名はhandleで始まり、取り扱いたいStripeのWebフックを続けます。例えば、invoice.payment_succeeded Webフックを使用したいのなら、コントローラーにはhandleInvoicePaymentSucceededメソッドを追加しなければなりません。

class WebhookController extends Laravel\Cashier\WebhookController {

    public function handleInvoicePaymentSucceeded($payload)
    {
        // そのイベントを処理する
    }

}

注意：データベースの中の購読情報を追加で更新すると、Webフックコントローラーは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',
]);

Laravel 4.2 Laravelキャッシャー