README

简介

Cashier Fastspring 是一个类似于收银台的 Laravel 扩展包，它提供了一个接口来访问 Fastspring 订阅和支付服务。此包处理 webhooks 并为 Fastspring 提供简单的 API。在开始使用此包之前，强烈建议查看 Fastspring 文档。

安装

将 bgultekin/cashier-fastspring 包添加到您的依赖项中。

composer require "bgultekin/cashier-fastspring"

在需要包之后，将此包的服务提供者添加到 config/app.php 文件中的提供者中。

'providers' => array(
    // ...
    Bgultekin\CashierFastspring\CashierServiceProvider::class,
)

配置

迁移

Cashier Fastspring 包附带数据库迁移。在需要包之后，您可以使用以下命令发布它。

php artisan vendor:publish

发布后，您可以在您的 database/migrations 文件夹中找到迁移文件。请记住，您可以根据需要修改它们。

可计费模型

接下来，将 Billable 特性添加到您的模型定义中。此特性提供了各种方法，允许您执行常见的计费任务，例如创建和检查订阅、获取订单等。

use Laravel\Cashier\Billable;

class User extends Authenticatable
{
    use Billable;
}

API 密钥

您应该将 Fastspring 配置添加到 config/services.php 文件中。

'fastspring' => [
    'model' => App\User::class,
    'username' => env('FASTSPRING_USERNAME'),
    'password' => env('FASTSPRING_PASSWORD'),
    'store_id' => env('FASTSPRING_STORE_ID'),

    // strongly recommend to set hmac secret in webhook configuration
    // to prevent webhook spoofing
    'hmac_secret' => env('FASTSPRING_HMAC_SECRET')
],

Webhook 路由

Fastspring 可以通过 webhooks 通知您的应用程序各种事件。要处理 webhooks，请定义一个路由，并在 Fastspring 设置中设置它。

Route::post(
    'fastspring/webhook',
    '\Bgultekin\CashierFastspring\Http\Controllers\WebhookController@handleWebhook'
)->name('fastspringWebhook');

Webhooks & CSRF 保护

Fastspring webhook 请求需要绕过 CSRF 保护。因此，请确保将您的 webhook URI 列为 VerifyCsrfToken 中间件的异常。

protected $except = [
    'fastspring/*',
];

创建计划

此包不涵盖在 Fastspring 端创建计划或将创建的计划存储。您应该在 Fastspring 的仪表板上创建您的订阅计划。

快速入门

Cashier Fastspring 包含内置的监听器，您可以在 src/Events 中找到它们以快速入门。这些监听器帮助您同步订阅和发票与您的数据库。

请记住，您可以根据需要创建和使用您的监听器和数据库结构。为了进行自定义，您可以查看用法。

在 Cashier Fastspring 中，每个 webhook 请求都会触发相关的事件。您可以在 app/providers/EventServiceProvider.php 中注册 webhook 事件的监听器。您可以在 Webhooks 中查看更多信息。

protected $listen = [
    // some others
    'Bgultekin\CashierFastspring\Events\SubscriptionCanceled' => [
        'Bgultekin\CashierFastspring\Listeners\SubscriptionStateChanged'
    ],
    'Bgultekin\CashierFastspring\Events\SubscriptionDeactivated' => [
        'Bgultekin\CashierFastspring\Listeners\SubscriptionDeactivated'
    ],
    'Bgultekin\CashierFastspring\Events\SubscriptionPaymentOverdue' => [
        'Bgultekin\CashierFastspring\Listeners\SubscriptionStateChanged'
    ],
    'Bgultekin\CashierFastspring\Events\OrderCompleted' => [
        'Bgultekin\CashierFastspring\Listeners\OrderCompleted'
    ],
    'Bgultekin\CashierFastspring\Events\SubscriptionActivated' => [
        'Bgultekin\CashierFastspring\Listeners\SubscriptionActivated'
    ],
    'Bgultekin\CashierFastspring\Events\SubscriptionChargeCompleted' => [
        'Bgultekin\CashierFastspring\Listeners\SubscriptionChargeCompleted'
    ]
];

您应该为订阅支付页面创建一个会话。您可以使用以下 newSubscription 方法来完成此操作。

// we create session and return it to frontend to care
$builder = Auth::user()->newSubscription('default', $selectedPlan);
$session = $builder->create();

您可以将会话 ID $session->id 提供给 Fastspring 的弹出式店面或 Web Storefronts。

注意：newSubscription方法不会创建订阅模型。在支付成功后，您可以使用webhooks或浏览器脚本通知您的应用程序并创建相关模型。

用法

Cashier Fastspring附带可立即使用的Subscription、Subscription Period、Invoice模型和webhook处理程序。以下为详细说明。请记住，您可以用自己的模型和逻辑轻松替换这些。

Cashier Fastspring提供了一种local类型的订阅，允许您在不与Fastspring交互的情况下创建订阅。这可能有助于您创建无需支付信息的计划。如果一个订阅没有fastspring_id，它就会被标记为本地。您可以使用type()、isLocal()、isFastspring()方法检查类型。

创建订阅

要创建订阅，您可以使用Billable模型的newSubscription方法。创建会话后，您可以将会话ID$session->id提供给Fastspring的弹出商店或网页商店。

// we create session and return it to frontend to care
$builder = Auth::user()->newSubscription('default', $selectedPlan);
$session = $builder->create();

您还可以提供优惠券或数量。提示：优惠券也可以在Fastspring的支付页面上设置。

$builder = Auth::user()->newSubscription('default', $selectedPlan)
    ->withCoupon('free-ticket-to-Mars')
    ->quantity(1); // yeap no ticket for returning
$session = $builder->create();

如果Billable模型尚未作为Fastspring客户创建，则newSubscription模型会自动创建并保存fastspring_id。如果您想手动执行此操作，可以使用createAsFastspringCustomer方法。

$apiResponse = Auth::user()->createAsFastspringCustomer();

如果Billable模型的详细信息已更新，您也可以使用updateAsFastspringCustomer方法在Fastspring端更新它们。

$apiResponse = Auth::user()->updateAsFastspringCustomer();

检查订阅状态

在Fastspring端，订阅有5个状态：active（活跃）、overdue（逾期）、canceled（已取消）、deactivated（已停用）、trial（试用）。您唯一需要放弃的状态是deactivated状态。其他只是信息状态。Cashier Fastspring包通过webhooks保持订阅状态的同步。

您可以使用subscribed方法检查是否应该继续为Billable模型提供服务。

if ($user->subscribed('default')) {
    //
}

您可以使用subscription方法检索相关订阅模型，并使用Subscription方法的方法检查其状态。

$subscription = $user->subscription('default');

// check if you should serve or not
$subscription->valid();

// check if its state is active
$subscription->active();

// check if its state is deactived
$subscription->deactivated();

// check if its state is overdue
$subscription->overdue();

// alias: onTrial(). check if its state is trial
$subscription->trial();

// alias: canceled(), onGracePeriod(). check if its state is canceled
$subscription->cancelled();

您可以使用subscribedToPlan方法检查用户是否订阅了指定的计划。

if ($user->subscribedToPlan('monthly', 'default')) {
    //
}

更改计划

您可以使用swap方法更改Billable模型的当前计划，如下所示。在这样做之前，建议您查看升级或降级订阅计划时的计费。

$user = App\User::find(1);

$user->subscription('default')->swap('provider-plan-id', $prorate, $quantity, $coupons);

swap方法与Fastspring通信，并根据响应更新订阅模型。如果您计划在不进行计费的情况下交换计划，则计划不会立即更改。在这种情况下，未来的计划和交换日期将保存到swap_to和swap_at列。当前订阅期的结束时，Fastspring会向您发送关于订阅更改的webhook请求。这就是为什么如果您认为要使用计费，请记住正确设置webhooks。

订阅试用

您可以在Fastspring仪表板上处理计划的试用天数。

取消订阅

要取消订阅，请在订阅模型上调用cancel方法。

$user->subscription('default')->cancel();

如果您想立即取消订阅，可以使用cancelNow方法。

$user->subscription('default')->cancelNow();

这两种方法都会根据Fastspring的响应更新订阅模型。cancel方法将取消时间保存到swap_at列。

恢复订阅

要恢复订阅，您可以在订阅模型上使用resume方法。用户必须仍在宽限期内。否则，此方法会抛出LogicException。

$user->subscription('default')->resume();

此方法根据响应更新订阅模型的state以及设置swap_to、swap_at列的值为null。

订阅周期

Cashier Fastspring包也内置了订阅周期模型和相关方法，以便帮助您管理订阅的支付周期。这可以帮助您在支付周期之间保持用户特定资源的使用。

您可以通过调用Subscription模型的activePeriodOrCreate方法来检索当前的SubscriptionPeriod模型，该模型包含id、start_date和end_date信息。如果当前活动周期尚未创建，此方法将从Fastspring API获取并创建。如果订阅是本地订阅，它还将根据最后一个订阅周期创建一个新的周期（如果没有，则假设今天是订阅周期的开始日）。

$activePeriod = $user->subscription('default')->activePeriodOrCreate();

// if you don't want to create an active subscription period immediately when no exist
// you can use activePeriod method as below
// you can set a cron job for creation of new periods 
// or do it in your way
$activePeriod = $user->subscription('default')->activePeriod();

更新信用卡

Fastspring不提供任何API直接更新信用卡或其他支付信息。您应将客户重定向到Fastspring侧的账户管理面板。您可以通过使用Billable模型的accountManagementURI方法生成账户管理面板URL。

$redirectURI = $user->accountManagementURI();

Webhooks

Cashier Fastspring包提供了一个处理webhooks的简单方法。它为每个webhook请求触发相关事件，并将请求负载数据作为参数提供。如果您设置了FASTSPRING_HMAC_SECRET，它还会处理消息安全。您可以在src/Listeners文件夹中找到示例监听器。

除了特定于webhook的事件之外，还有类别和任何事件。例如，如果您想监听所有webhook请求，您可以注册监听器到Bgultekin\CashierFastspring\Events\Any事件。另外，如果您想监听所有与订阅相关的webhook请求，您可以使用Bgultekin\CashierFastspring\Events\SubscriptionAny事件。

您可以在下表中查看包事件与webhook请求之间的关系。

要监听事件，您可以在app/providers/EventServiceProvider.php中注册监听器。

protected $listen = [
    // some others
    'Bgultekin\CashierFastspring\Events\SubscriptionCanceled' => [
        'Your\Lovely\Listener'
    ]
];

单次收费

尚未实现。如果您需要它，您可以为此包做出贡献。请查看贡献。

发票

在Fastspring中，发票由Fastspring生成。您不需要生成官方或非官方的发票。如果您使用默认的webhook监听器，您的发票将同步到您的数据库。您可以使用Invoice模型或通过Billable特性行获取发票URL。

贡献

感谢您考虑为Cashier Fastspring做出贡献。您可以在这里阅读贡献指南。您还可以检查问题以改进此包。

鸣谢

Cashier Fastspring包是由Bilal Gultekin基于Taylor Otwell的Cashier包开发的。您可以在这里查看所有贡献者。

许可证

Cashier Fastspring是开源软件，根据MIT许可证授权。

bgultekin / cashier-fastspring

维护者

详细信息