Laravel Cashier のコア特性を理解する: ディープダイブ

Laravel Cashier は、Stripe 統合を処理するいくつかの強力な特性を提供します。今日は、ManagesSubscriptions、ManagesCustomer、および ManagesInvoices の 3 つのコア特性とそのパブリック メソッドについて説明します。 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')

• $type だけ: 有効なサブスクリプションの存在を確認します
• $price を使用: 特定の価格のサブスクリプションを確認します
• ブール値を返します

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

• タイプごとにサブスクリプションを取得します
• サブスクリプション モデルまたは null を返します

subscription($type = 'default')

• すべてのサブスクリプションを取得します
• HasMany 関係を返します
• パラメータは必要ありません

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-> メールが返されます

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()

• クレジット顧客残高
• CustomerBalanceTransaction を返します
• 金額は必須です

scopeHasExpiredGenericTrial($query)

• 顧客残高の借方
• CustomerBalanceTransaction を返します
• 金額は必須です

trialEndsAt($type = 'default')

• バランス調整を適用します
• CustomerBalanceTransaction を返します
• 金額は必須です

税務管理

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 請求ポータルにリダイレクトします
• RedirectResponse を返します
• ReturnUrl オプション

ManagesInvoices 特性

請求書項目

priceTaxRates()

• 請求書項目を追加します
• Stripe InvoiceItem を返します
• 説明と必要な量

stripeId()

• 価格ベースの項目を追加します
• Stripe InvoiceItem を返します
• 価格 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 中国語 Web サイトの他の関連記事を参照してください。