为何选择 Laravel Cashier？
在处理 stripe 支付时，开发者经常需要在应用程序中管理客户数据。虽然 stripe 提供了完善的 restful api 供直接调用，但 laravel cashier 作为官方的订阅管理包，为与 stripe 的交互提供了高度抽象和便捷的接口。通过 cashier，开发者可以避免编写大量的重复代码来处理 api 请求、响应解析和错误处理，从而使业务逻辑更聚焦、代码更简洁。尤其是在删除 stripe 客户这类操作上，cashier 提供的内置方法比直接使用 guzzle 等 http 客户端调用 stripe api 更具优势，它将复杂的底层操作封装成一行代码，极大地提升了开发效率和代码可读性。
核心方法：asStripeCustomer()->delete()
Laravel Cashier 假设你的用户模型（或其他可计费模型）具有 Billable trait，并且包含 stripe_id 字段来存储对应的 Stripe 客户 ID。当需要删除一个 Stripe 客户时，Cashier 提供了直接在模型实例上操作的便捷方法。
核心操作流程如下：
- 获取可计费模型实例： 首先，你需要获取到代表该 Stripe 客户的本地用户模型实例。
- 检查 stripe_id： 确保该用户模型确实关联了一个 Stripe 客户 ID (stripe_id 字段不为空)。
- 调用 asStripeCustomer()： 这个方法会基于模型实例的 stripe_id，从 Stripe 获取对应的 Stripe\Customer 对象。
- 调用 delete()： 在获取到的 Stripe\Customer 对象上调用 delete() 方法，即可向 Stripe 发送删除客户的请求。
实现步骤与示例代码
以下是一个在 Laravel 应用程序中实现删除 Stripe 客户的示例函数：
<?php
namespace App\Services; // 假设这是一个服务类
use App\Models\User; // 假设你的可计费模型是 App\Models\User
use Stripe\Exception\ApiErrorException; // 引入 Stripe API 错误异常
class StripeCustomerService
{
/**
* 删除 Stripe 平台上的客户及其相关数据。
*
* @param User $user 需要删除 Stripe 客户的用户实例
* @return bool 删除操作是否成功
* @throws ApiErrorException 如果 Stripe API 调用失败
*/
public function deleteStripeCustomer(User $user): bool
{
// 1. 检查用户是否关联了 Stripe 客户 ID
if (empty($user->stripe_id)) {
// 如果没有 Stripe ID，则无需执行删除操作
// 可以在此处记录日志或抛出特定异常
return true; // 视为成功，因为没有需要删除的 Stripe 客户
}
try {
// 2. 获取 Stripe 客户实例并调用 delete 方法
// asStripeCustomer() 会返回一个 Stripe\Customer 对象
$stripeCustomer = $user->asStripeCustomer();
$stripeCustomer->delete();
// 3. (可选但推荐) 清除本地数据库中与 Stripe 客户相关的字段
// 这确保了本地数据与 Stripe 平台状态的一致性
$user->forceFill([
'stripe_id' => null,
'pm_type' => null, // 清除默认支付方式类型
'pm_last_four' => null, // 清除默认支付方式后四位
// 根据你的 Cashier 配置，可能还需要清除其他相关字段，
// 例如 subscription_name, subscription_stripe_id, subscription_stripe_status 等
])->save();
return true; // 删除成功
} catch (ApiErrorException $e) {
// 处理 Stripe API 错误，例如网络问题、API 密钥无效等
// 可以在此处记录错误日志，并重新抛出或返回 false
\Log::error("删除 Stripe 客户失败: 用户ID {$user->id}, 错误信息: {$e->getMessage()}");
throw $e; // 重新抛出异常以便上层调用者处理
} catch (\Exception $e) {
// 处理其他潜在的 PHP 错误
\Log::error("删除 Stripe 客户时发生未知错误: 用户ID {$user->id}, 错误信息: {$e->getMessage()}");
throw $e;
}
}
}
// 如何在控制器或服务中使用：
// use App\Models\User;
// use App\Services\StripeCustomerService;
// public function destroyUserAccount(User $user, StripeCustomerService $stripeCustomerService)
// {
// try {
// $stripeCustomerService->deleteStripeCustomer($user);
// // 用户账号的其他删除逻辑...
// return redirect()->back()->with('success', '用户及其 Stripe 客户已成功删除。');
// } catch (\Exception $e) {
// return redirect()->back()->with('error', '删除用户失败：' . $e->getMessage());
// }
// }重要注意事项
- 本地数据同步： asStripeCustomer()->delete() 方法仅负责删除 Stripe 平台上的客户数据。为了保持应用程序数据的一致性，你需要在成功删除 Stripe 客户后，手动清除或更新本地数据库中用户模型上的 stripe_id 字段以及其他可能与 Stripe 相关的字段（如 pm_type, pm_last_four 等）。示例代码中已包含此步骤。
-
Stripe 关联数据删除： 当一个 Stripe 客户被删除时，Stripe 会自动删除该客户名下所有关联的资源，包括：
- 支付方式 (Payment Methods)
- 订阅 (Subscriptions)
- 发票 (Invoices)
- 支付意图 (Payment Intents)
- 退款 (Refunds)
- 等等。 这是一个不可逆的操作，请务必谨慎执行。
- 错误处理与健壮性： 在生产环境中，任何与外部 API 的交互都应包含完善的错误处理机制。使用 try-catch 块捕获 Stripe\Exception\ApiErrorException 或其他通用异常，能够有效应对网络问题、API 密钥失效、权限不足等情况，确保应用程序的健壮性。
- 权限与用户确认： 删除客户是一个高风险操作。在实际应用中，应确保只有具备足够权限的用户（如管理员）才能执行此操作，并且最好在执行前向操作者提供明确的确认提示。
- 软删除与硬删除： 如果你的应用程序对用户模型采用了软删除 (Soft Deletes)，你需要仔细考虑何时删除 Stripe 客户。通常，只有当用户被永久删除（硬删除）时，才应该从 Stripe 删除对应的客户。如果只是软删除，用户数据仍在本地，那么其 Stripe 客户信息也应保留，以备将来恢复。
总结
Laravel Cashier 通过其简洁的 API，极大地简化了与 Stripe 服务的集成。通过 asStripeCustomer()->delete() 方法，开发者可以优雅且高效地管理 Stripe 客户的生命周期，确保代码的整洁和可维护性。然而，在享受便捷的同时，也务必重视数据同步、错误处理以及操作的不可逆性，以构建一个稳定可靠的支付系统。
