laravel-cashier-stripe

Laravel Cashier (Stripe) スキル

Laravel アプリケーションにおけるサブスクリプション請求、決済処理、Stripe 連携のための Laravel Cashier (Stripe) 開発を包括的に支援します。

このスキルを使用するタイミング

以下の場合に、このスキルを使用してください：

• Laravel アプリケーションでサブスクリプション請求を実装する
• Stripe で定期決済を設定する
• 顧客のサブスクリプション、トライアル、プラン変更を管理する
• 1 回限りの請求や請求書を処理する
• Stripe の Webhook やイベントを処理する
• Stripe Checkout を使ったチェックアウトフローを実装する
• 顧客の支払い方法やカードを管理する
• Stripe の請求書や請求ポータルを扱う
• トライアル期間や日割り計算のロジックを設定する
• Laravel の Stripe 連携に関する問題をデバッグする

クイックリファレンス

インストールとセットアップ

# Install Cashier
composer require laravel/cashier

# Publish migrations and migrate
php artisan vendor:publish --tag="cashier-migrations"
php artisan migrate

# Publish config (optional)
php artisan vendor:publish --tag="cashier-config"

課金可能なモデルを設定する

use Laravel\Cashier\Billable;

class User extends Authenticatable
{
    use Billable;
}

サブスクリプションを作成する

// Basic subscription with trial and checkout
$user->newSubscription('default', 'price_monthly')
    ->trialDays(5)
    ->allowPromotionCodes()
    ->checkout([
        'success_url' => route('checkout.success'),
        'cancel_url' => route('checkout.cancel'),
    ]);

サブスクリプションのステータスを確認する

// Check if user has active subscription
if ($user->subscribed('default')) {
    // User is subscribed to "default" plan
}

// Check specific product subscription
if ($user->subscribedToProduct('prod_premium', 'default')) {
    // User is subscribed to premium product
}

// Check trial status
if ($user->subscription('default')->onTrial()) {
    // User is still in trial period
}

支払い方法を管理する

// Store payment method (in view with Stripe.js)
$intent = $user->createSetupIntent();

// Retrieve payment methods
$paymentMethods = $user->paymentMethods();
$defaultMethod = $user->defaultPaymentMethod();

// Add and update payment methods
$user->addPaymentMethod($paymentMethodId);
$user->updateDefaultPaymentMethod($paymentMethodId);

サブスクリプションのプランを切り替える

// Swap to different price/plan
$user->subscription('default')->swap('price_yearly');

// Swap and skip trial
$user->subscription('default')->skipTrial()->swap('price_yearly');

1 回限りの請求と請求書

// One-time charge
$user->charge(1000, $paymentMethodId, [
    'description' => 'One-time charge',
]);

// Create invoice for service
$user->invoiceFor('Premium Support', 5000, [
    'description' => '3 months of premium support',
]);

// Refund a charge
$user->refund($chargeId);

サブスクリプションをキャンセルする

// Cancel immediately
$user->subscription('default')->cancel();

// Cancel at end of billing period
$user->subscription('default')->cancelAtEndOfBillingPeriod();

// Resume canceled subscription
if ($user->subscription('default')->onGracePeriod()) {
    $user->subscription('default')->resume();
}

請求書を扱う

// Get all invoices
$invoices = $user->invoices();

// Get upcoming invoice
$upcomingInvoice = $user->upcomingInvoice('default');

// Download invoice PDF
return $user->invoices()->first()->download();

請求ポータルを連携する

// Redirect to Stripe billing portal
Route::get('/billing', function (Request $request) {
    return $request->user()
        ->redirectToBillingPortal(route('dashboard'));
})->middleware(['auth']);

顧客を管理する

// Create/get Stripe customer
$stripeCustomer = $user->createOrGetStripeCustomer();

// Update customer details
$user->updateStripeCustomer([
    'name' => 'Updated Name',
    'email' => '[email protected]',
]);

// Manage tax IDs
$taxId = $user->createTaxId('eu_vat', 'BE0123456789');
$user->deleteTaxId('txi_belgium');

主な概念

課金可能なモデル

Billable トレイトを使うと、Eloquent モデル（通常は User）にサブスクリプションおよび決済機能を追加できます。サブスクリプションの作成、請求処理、支払い方法の管理、請求書へのアクセスに使えるメソッドが提供されます。

サブスクリプション

Cashier はサブスクリプションを通じて定期請求を管理します。各サブスクリプションには、以下の情報があります：

• 名前：「default」や「premium」などの識別子
• 価格 ID：Stripe の価格識別子（例：「price_monthly」）
• ステータス：有効、トライアル中、キャンセル済み、未完了など
• トライアル期間：課金開始前に設定できる任意のトライアル日数
• 従量課金：使用量に応じた価格設定への対応

支払い方法

Stripe の支払い方法は、保存済みの支払い認証情報（カード、銀行口座）を表します。Cashier には、以下の操作に使えるヘルパーが用意されています：

• Setup Intents を使って支払い方法を安全に保存する
• サブスクリプションのデフォルトの支払い方法を設定する
• 支払い方法を更新、削除する
• 支払い方法の確認を処理する

Webhook

Stripe は、サブスクリプションの変更、決済の失敗、請求書の更新などに関する Webhook イベントを送信します。Cashier は一般的な Webhook を自動的に処理しますが、特定のイベントをリッスンして機能を拡張することもできます。

Checkout セッション

Stripe Checkout は、あらかじめ構築された決済ページを提供します。Cashier を使うと、サブスクリプションや 1 回限りの商品に対する Checkout セッションを簡単に作成でき、最小限のコードで決済フロー全体を処理できます。

請求書

Cashier を使うと、サブスクリプションと 1 回限りの請求の両方について、Stripe の請求書にアクセスできます。請求書の取得、プレビュー、PDF としてのダウンロードが可能です。

リファレンスファイル

このスキルには、references/ に包括的なドキュメントが含まれています：

• other.md - 以下を網羅した Laravel Cashier の完全なドキュメント：
  • インストールと設定
  • サブスクリプション管理（作成、切り替え、キャンセル、再開）
  • 支払い方法の処理と Setup Intents
  • 1 回限りの請求と請求書発行
  • Stripe Checkout との連携
  • Webhook の処理とイベント処理
  • 顧客ポータルとの連携
  • 税 ID の管理
  • テスト戦略

特定の機能について詳しく知りたい場合は、view を使ってリファレンスファイルを読んでください。

このスキルの使い方

初心者向け

まず、以下を行ってください：

1. Cashier をインストールして、マイグレーションを実行する
2. User モデルに Billable トレイトを追加する
3. 環境変数（STRIPE_KEY、STRIPE_SECRET）を設定する
4. newSubscription() で最初のサブスクリプションを作成する
5. Stripe のテストモードの API キーを使ってテストする

基本的なワークフロー：

// 1. Configure model
use Laravel\Cashier\Billable;
class User extends Authenticatable { use Billable; }

// 2. Create subscription
$user->newSubscription('default', 'price_monthly')->create();

// 3. Check status
if ($user->subscribed('default')) {
    // Grant access
}

中級ユーザー向け

以下に重点を置きます。

• Stripe Checkout を使用した完全なチェックアウトフローの実装
• 支払い方法の変更と更新の管理
• サブスクリプションプランの変更と日割り計算への対応
• トライアル期間と猶予期間への対応
• サブスクリプションと併せた単発請求の処理
• 請求書の詳細と税情報のカスタマイズ

上級ユーザー向け

以下をご確認ください。

• Webhook イベントのカスタマイズと拡張処理
• 従量課金と使用量ベースの料金設定
• 複数プランのサブスクリプション（ユーザーごとに複数のサブスクリプション）
• 顧客残高とクレジットの管理
• 税 ID の検証とコンプライアンス
• 請求書の高度なカスタマイズ
• マーケットプレイス向けの Stripe Connect 統合
• サブスクリプションフローのテスト戦略

ナビゲーションのヒント

• よくあるタスクについては、クイックリファレンスのセクションから始めてください
• Cashier の主要な用語を理解するには、「主要な概念」を確認してください
• 実装の詳細については、references/other.md を参照してください
• 最新情報については、公式の Laravel Cashier ドキュメント（https://laravel.com/docs/12.x/billing）を参照してください

環境設定

.env で必要な環境変数：

STRIPE_KEY=pk_test_your_stripe_publishable_key
STRIPE_SECRET=sk_test_your_stripe_secret_key
STRIPE_WEBHOOK_SECRET=whsec_your_webhook_signing_secret
CASHIER_CURRENCY=usd

重要： 開発時にはテストモードのキー（pk_test_、sk_test_）を使用し、本番環境ではライブキー（pk_live_、sk_live_）に切り替えてください。

よくあるパターン

サブスクリプションの完全なチェックアウトフロー

// 1. Create checkout session
public function subscribe(Request $request)
{
    return $request->user()
        ->newSubscription('default', 'price_monthly')
        ->trialDays(14)
        ->allowPromotionCodes()
        ->checkout([
            'success_url' => route('checkout.success') . '?session_id={CHECKOUT_SESSION_ID}',
            'cancel_url' => route('checkout.cancel'),
        ]);
}

// 2. Handle success
public function success(Request $request)
{
    $sessionId = $request->get('session_id');

    if ($request->user()->subscribed('default')) {
        return redirect()->route('dashboard')
            ->with('success', 'Subscription activated!');
    }
}

アップグレード／ダウングレードのパターン

// Upgrade to annual plan with prorated credit
public function upgrade(Request $request)
{
    $subscription = $request->user()->subscription('default');

    if ($subscription->active()) {
        $subscription->swap('price_yearly');
        return back()->with('success', 'Upgraded to annual plan!');
    }
}

支払い方法の更新フロー

// Controller: Generate setup intent
public function paymentMethods(Request $request)
{
    return view('billing.payment-methods', [
        'intent' => $request->user()->createSetupIntent(),
        'paymentMethods' => $request->user()->paymentMethods(),
    ]);
}

// View: Stripe.js integration (Blade)
<form id="payment-form" method="POST" action="{{ route('payment-method.add') }}">
    @csrf
    <div id="card-element"></div>
    <button type="submit">Add Payment Method</button>
</form>

// Controller: Store payment method
public function addPaymentMethod(Request $request)
{
    $request->user()->addPaymentMethod($request->payment_method);
    return back()->with('success', 'Payment method added!');
}

リソース

公式ドキュメント

• Laravel Cashier（Stripe）：https://laravel.com/docs/12.x/billing
• Stripe API ドキュメント：https://stripe.com/docs/api
• Stripe テストガイド：https://stripe.com/docs/testing

テスト

開発時には Stripe のテストカード番号を使用してください。

• 成功：4242 4242 4242 4242
• 決済拒否：4000 0000 0000 0002
• 認証が必要：4000 0025 0000 3155

開発とテストでは、必ずテストモードの API キーを使用してください。

注意事項

• Cashier には PHP 8.1 以降と Laravel 10.0 以降が必要です
• 信頼性の高いサブスクリプション管理のため、本番環境では必ず Webhook を設定してください
• 開発時には Stripe のテストモードを使用してください
• Billable トレイトは User だけでなく、あらゆる Eloquent モデルに追加できます
• Cashier はほとんどの Webhook イベントを自動的に処理します
• 顧客がセルフサービスで利用できるよう、Stripe の請求ポータルの使用をご検討ください
• リファレンスファイルには、公式 Laravel ドキュメントの構成と例が保持されています
• 本番環境に移行する前に、サブスクリプションフローを十分にテストしてください

更新

このスキルは Laravel 12.x 向けの Laravel Cashier に基づいています。最新情報については、公式ドキュメント（https://laravel.com/docs/billing）を参照してください。