了解 Laravel Cashier 的核心特征：深入探讨

Laravel Cashier 提供了几个处理 Stripe 集成的强大特性。今天，我们将探讨三个核心特征及其公共方法：ManagesSubscriptions、ManagesCustomer 和 ManagesInvoices。了解这些特征对于在 Laravel 应用程序中实现基于订阅的计费至关重要。

管理订阅特征

订阅创建和管理

newSubscription($type, $prices = [])

创建新的订阅构建器实例。类型定义订阅名称（例如“默认”），价格可以是单个 ID 或数组。

试验管理

newSubscription($type, $prices = [])

• 无参数：仅检查通用（模型级）试验
• 使用 $type：检查特定于订阅的试用
• 同时使用：检查特定价格是否处于试用状态
• 返回布尔值

onTrial($type = 'default', $price = null)

• 无参数：检查通用试用期
• 使用 $type：检查特定订阅试用期
• 同时使用：验证具体价格试用期
• 返回布尔值

hasExpiredTrial($type = 'default', $price = null)

• 检查模型级试用状态
• 如果 Trial_ends_at 存在且为未来，则返回 true
• 无需参数

onGenericTrial()

• 筛选通用试用客户的范围
• 用于查询生成器
• 需要查询构建器实例

scopeOnGenericTrial($query)

• 检查模型级试用是否已过期
• 如果 Trial_ends_at 存在且已过去，则返回 true
• 无需参数

hasExpiredGenericTrial()

• 过滤仿制药过期客户的范围
• 用于查询生成器
• 需要查询构建器实例

scopeHasExpiredGenericTrial($query)

• 无参数：如果进行通用试用，则返回通用试用结束日期
• 使用 $type：返回订阅特定的试用结束日期
• 返回 Carbon 实例或 null

订阅状态检查

trialEndsAt($type = 'default')

• Just $type：检查有效订阅是否存在
• With $price：检查具体价格订阅
• 返回布尔值

subscribed($type = 'default', $price = null)

• 按类型获取订阅
• 返回订阅模型或 null

subscription($type = 'default')

• 获取所有订阅
• 返回有很多关系
• 无需参数

subscriptions()

• 检查订阅付款是否不完整
• 返回布尔值

hasIncompletePayment($type = 'default')

• $products：单个产品 ID 或数组
• $type：要检查的订阅类型
• 返回布尔值
• 检查是否订阅了任何给定产品

subscribedToProduct($products, $type = 'default')

• $prices：单个价格 ID 或数组
• $type：要检查的订阅类型
• 返回布尔值
• 检查是否订阅了任何给定的价格

subscribedToPrice($prices, $type = 'default')

• 检查特定产品的有效订阅
• 返回布尔值
• 比 subscribedToProduct 更具体

onProduct($product)

• 检查特定价格的有效订阅
• 返回布尔值
• 比 subscribedToPrice 更具体

onPrice($price)

• 获取订阅税率
• 返回数组
• 默认为空，需要被覆盖

taxRates()

• 获取单个订阅项目的税率
• 返回数组
• 默认为空，需要被覆盖

管理客户特征

客户识别

newSubscription($type, $prices = [])

• 返回 Stripe 客户 ID 或 null
• 无需参数
• 返回字符串|null

onTrial($type = 'default', $price = null)

• 检查客户是否有 Stripe ID
• 返回布尔值
• 无需参数

客户创建和管理

hasExpiredTrial($type = 'default', $price = null)

• 创建新的 Stripe 客户
• 选项影响客户元数据、电子邮件、姓名等
• 如果客户已存在则抛出异常
• 返回 Stripe Customer 对象

onGenericTrial()

• 更新现有 Stripe 客户
• 选项决定更新内容
• 返回更新后的 Stripe Customer 对象
• 需要现有客户

scopeOnGenericTrial($query)

• 获取现有客户或创建新客户
• 如果需要，选项会影响创建
• 返回 Stripe Customer 对象
• 比 createAsStripeCustomer 更宽容

hasExpiredGenericTrial()

• 更新现有客户或创建新客户
• 选项会影响更新和创建
• 返回 Stripe Customer 对象
• 结合了更新和创建功能

scopeHasExpiredGenericTrial($query)

• 将本地详细信息同步到 Stripe
• 返回 Stripe Customer 对象
• 使用模型属性进行同步

trialEndsAt($type = 'default')

• 同步（如果存在）或创建新客户
• 如果需要，选项会影响创建
• 返回 Stripe Customer 对象

subscribed($type = 'default', $price = null)

• 获取 Stripe 客户对象
• 展开参数确定相关数据
• 返回 Stripe Customer 对象
• 需要现有客户

客户属性

subscription($type = 'default')

• 获取 Stripe 同步的名称
• 返回字符串|null
• 默认返回$this->name

subscriptions()

• 获取 Stripe 同步电子邮件
• 返回字符串|null
• 默认返回$this->email

hasIncompletePayment($type = 'default')

• 获取手机进行 Stripe 同步
• 返回字符串|null
• 默认返回$this->phone

subscribedToProduct($products, $type = 'default')

• 获取 Stripe 同步地址
• 返回数组|null
• 默认为空

subscribedToPrice($prices, $type = 'default')

• 获取 Stripe 的首选区域设置
• 返回数组
• 默认为空

onProduct($product)

• 获取 Stripe 的元数据
• 返回数组
• 默认为空

折扣管理

onPrice($price)

• 获得活跃客户折扣
• 返回折扣对象或 null
• 无需参数

taxRates()

• 向客户应用优惠券
• 无效退货
• 需要优惠券 ID

priceTaxRates()

• 向客户应用促销代码
• 无效退货
• 需要促销代码 ID

newSubscription($type, $prices = [])

• 找到促销代码
• 返回 PromotionCode 对象或 null
• 选项影响搜索

onTrial($type = 'default', $price = null)

• 找到有效的促销代码
• 返回 PromotionCode 对象或 null
• 影响搜索的选项

余额管理

hasExpiredTrial($type = 'default', $price = null)

• 获取格式化的客户余额
• 返回字符串
• 无需参数

onGenericTrial()

• 获取原始客户余额
• 返回整数
• 无需参数

scopeOnGenericTrial($query)

• 获取客户余额交易
• 退货集合
• 限制影响返回计数

hasExpiredGenericTrial()

• 贷记客户余额
• 返回客户余额交易
• 金额为必填项

scopeHasExpiredGenericTrial($query)

• 借记客户余额
• 返回客户余额交易
• 金额为必填项

trialEndsAt($type = 'default')

• 应用平衡调整
• 返回客户余额交易
• 金额为必填项

税务管理

subscribed($type = 'default', $price = null)

• 获取客户税号
• 退货集合
• 选项影响检索

subscription($type = 'default')

• 创建新的税号
• 返回 Stripe TaxId
• 两个参数都是必需的

subscriptions()

• 删除税号
• 无效退货
• 需要税号

hasIncompletePayment($type = 'default')

• 查找特定税号
• 返回 Stripe TaxId 或 null
• 需要税号

税务状况检查

subscribedToProduct($products, $type = 'default')

• 检查客户是否不免税
• 返回布尔值
• 无需参数

subscribedToPrice($prices, $type = 'default')

• 检查客户是否免税
• 返回布尔值
• 无需参数

onProduct($product)

• 检查是否适用反向收费
• 返回布尔值
• 无需参数

计费门户

onPrice($price)

• 获取 Stripe 计费门户 URL
• 返回字符串
• ReturnUrl 可选

taxRates()

• 重定向到 Stripe 计费门户
• 返回重定向响应
• ReturnUrl 可选

管理发票特征

发票项目

priceTaxRates()

• 添加发票项目
• 返回 Stripe 发票项目
• 所需说明及金额

stripeId()

• 添加基于价格的商品
• 返回 Stripe 发票项目
• 需要价格 ID

发票创建

hasStripeId()

• 创建即时发票
• 返回发票对象
• 所需说明及金额

createAsStripeCustomer(array $options = [])

• 创建基于价格的发票
• 返回发票对象
• 需要价格 ID

newSubscription($type, $prices = [])

• 生成发票
• 返回发票对象
• 选项影响创作

onTrial($type = 'default', $price = null)

• 创建 Stripe 发票
• 返回发票对象
• 选项影响创作

发票检索

hasExpiredTrial($type = 'default', $price = null)

• 获取即将到来的发票
• 返回 Invoice 对象或 null
• 选项影响预览

onGenericTrial()

• 查找特定发票
• 返回 Invoice 对象或 null
• 需要发票 ID

scopeOnGenericTrial($query)

• 查找发票或抛出异常
• 返回发票对象
• 需要发票 ID
• 抛出 NotFoundHttpException 或 AccessDeniedHttpException

hasExpiredGenericTrial()

• 获取发票 PDF
• 返回响应
• ID 必填，文件名可选

scopeHasExpiredGenericTrial($query)

• 获取所有发票
• 退货集合
• 参数影响过滤

trialEndsAt($type = 'default')

• 获取所有发票，包括待处理的
• 退货集合
• 发票的简写（true）

subscribed($type = 'default', $price = null)

• 获取分页发票
• 返回 CursorPaginator
• 多个参数影响分页

主要观察结果

1. 参数敏感性：方法通常根据参数的存在而具有不同的行为。
2. 返回类型：方法始终返回特定类型（布尔值、对象、集合）。
3. 默认值：许多参数都有合理的默认值，但可以被覆盖。
4. 特征相互依赖：方法通常依赖于其他特征方法。
5. Stripe 集成：大多数方法直接或间接与 Stripe 的 API 交互。

最佳实践

1. 始终检查所需行为的参数要求。
2. 处理潜在的异常，尤其是 *OrFail 方法。
3. 扩展这些特征时使用正确的类型提示。
4. 彻底测试不同的参数组合。
5. 考虑缓存频繁调用以减少 API 请求。

结论

这些特征构成了 Laravel Cashier 功能的支柱。了解可用方法及其参数行为的全部范围对于正确实现至关重要。请务必参阅本参考资料的官方文档以获取最新信息。

以上是了解 Laravel Cashier 的核心特征：深入探讨的详细内容。更多信息请关注PHP中文网其他相关文章！