了解 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中文網其他相關文章！