laravel-cashier-stripe

Laravel Cashier (Stripe) 技能

全面协助在 Laravel 应用中使用 Laravel Cashier (Stripe) 进行订阅计费、支付处理和 Stripe 集成开发。

何时使用此技能

在以下情况下应触发此技能：

• 在 Laravel 应用中实现订阅计费
• 使用 Stripe 设置定期付款
• 管理客户订阅、试用期和套餐变更
• 处理一次性收费或发票
• 处理 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');

单次收费和发票

// 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 trait 为 Eloquent 模型（通常是 User）添加订阅和支付功能。它提供创建订阅、处理收费、管理付款方式以及访问发票的方法。

订阅

Cashier 通过订阅管理定期计费。每个订阅都包含：

• 名称：例如 “default” 或 “premium” 的标识符
• 价格 ID：Stripe 价格标识符（例如 “price_monthly”）
• 状态：有效、试用中、已取消、未完成等
• 试用期：可选的收费前试用天数
• 按量计费：支持基于用量的定价

付款方式

Stripe 付款方式代表已存储的支付凭据（银行卡、银行账户）。Cashier 提供以下辅助功能：

• 通过 Setup Intents 安全地存储付款方式
• 为订阅设置默认付款方式
• 更新和删除付款方式
• 处理付款方式验证

Webhook

Stripe 会针对订阅变更、付款失败、发票更新等情况发送 Webhook 事件。Cashier 会自动处理常见的 Webhook，但你也可以通过监听特定事件来扩展功能。

结账会话

Stripe Checkout 提供预构建的支付页面。Cashier 简化了为订阅和一次性商品创建结账会话的流程，只需少量代码即可处理完整的支付流程。

发票

Cashier 提供访问订阅和一次性收费对应 Stripe 发票的功能。你可以检索、预览和下载 PDF 格式的发票。

参考文件

此技能在 references/ 中包含完整文档：

• other.md - 完整的 Laravel Cashier 文档，涵盖：
  • 安装和配置
  • 订阅管理（创建、更换、取消、恢复）
  • 付款方式处理和 Setup Intents
  • 单次收费和开具发票
  • Stripe Checkout 集成
  • Webhook 处理和事件处理
  • 客户门户集成
  • 税号管理
  • 测试策略

需要了解特定功能的详细信息时，请使用 view 阅读参考文件。

使用此技能

入门指南

请从以下步骤开始：

1. 安装 Cashier 并运行迁移
2. 将 Billable trait 添加到你的 User 模型
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 事件并扩展其处理逻辑
• 按量计费和基于用量的定价
• 多方案订阅（每位用户拥有多个订阅）
• 客户余额和额度管理
• 税号验证与合规
• 高级发票自定义
• 将 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 trait 可添加到任何 Eloquent 模型，不仅限于 User
• Cashier 会自动处理大多数 Webhook 事件
• 可考虑使用 Stripe 的账单门户，让客户自行管理
• 参考文件保留了 Laravel 官方文档中的结构和示例
• 上线前请彻底测试订阅流程

更新

本技能基于适用于 Laravel 12.x 的 Laravel Cashier。有关最新信息，请参阅官方文档 https://laravel.com/docs/billing。