README

Wakjoko Subscriptions 是一个不依赖用户表的 rinvex/laravel-subscriptions 分支版本。您可以将订阅附加到任何模型中。

注意事项

• 此包不包括支付功能。
• 如果您需要重写一些辅助方法（如 renew()、cancel() 等）背后的逻辑，可能需要扩展一些核心模型。例如：在取消订阅时，您可能还想取消附加的周期性支付。

安装

1. 通过composer安装包

   composer require wakjoko/laravel-subscriptions

2. 发布资源（迁移和配置文件）

   php artisan wakjoko:publish:subscriptions

3. 执行以下命令进行迁移

   php artisan wakjoko:migrate:subscriptions

4. 完成！

用法

将订阅添加到User模型中

Wakjoko Subscriptions 特别针对Eloquent和简洁性进行了优化。要将订阅功能添加到您的User模型中，只需使用 \Wakjoko\Subscriptions\Traits\HasSubscriptions 特性，如下所示

namespace App\Models;

use Wakjoko\Subscriptions\Traits\HasSubscriptions;
use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable
{
    use HasSubscriptions;
}

就是这样，我们只需在我们的User模型中使用该特性！现在，您的用户可以订阅计划了。

创建计划

$plan = app('wakjoko.subscriptions.plan')->create([
    'name' => 'Pro',
    'description' => 'Pro plan',
    'price' => 9.99,
    'signup_fee' => 1.99,
    'invoice_period' => 1,
    'invoice_interval' => 'month',
    'trial_period' => 15,
    'trial_interval' => 'day',
    'sort_order' => 1,
    'currency' => 'USD',
]);

// Create multiple plan features at once
$plan->features()->saveMany([
    new PlanFeature(['name' => 'listings', 'value' => 50, 'sort_order' => 1]),
    new PlanFeature(['name' => 'pictures_per_listing', 'value' => 10, 'sort_order' => 5]),
    new PlanFeature(['name' => 'listing_duration_days', 'value' => 30, 'sort_order' => 10, 'resettable_period' => 1, 'resettable_interval' => 'month']),
    new PlanFeature(['name' => 'listing_title_bold', 'value' => 'Y', 'sort_order' => 15])
]);

获取计划详情

您可以使用直观的API查询计划的更多详细信息，如下所示

$plan = app('wakjoko.subscriptions.plan')->find(1);

// Get all plan features                
$plan->features;

// Get all plan subscriptions
$plan->subscriptions;

// Check if the plan is free
$plan->isFree();

// Check if the plan has trial period
$plan->hasTrial();

// Check if the plan has grace period
$plan->hasGrace();

Both $plan->features 和 $plan->subscriptions 都是集合，由关系驱动，因此您可以像查询任何正常的Eloquent关系一样查询这些关系。例如 $plan->features()->where('name', 'listing_title_bold')->first()。

获取功能值

假设您想显示上面 pictures_per_listing 功能的值。您可以通过多种方式做到这一点

// Use the plan instance to get feature's value
$amountOfPictures = $plan->getFeatureByName('pictures_per_listing')->value;

// Query the feature itself directly
$amountOfPictures = app('wakjoko.subscriptions.plan_feature')->where('name', 'pictures_per_listing')->first()->value;

// Get feature value through the subscription instance
$amountOfPictures = app('wakjoko.subscriptions.plan_subscription')->find(1)->getFeatureValue('pictures_per_listing');

创建订阅

您可以使用在 HasSubscriptions 特性中可用的 newSubscription() 函数来将可订阅对象订阅到一个计划。首先，检索您的订阅者模型实例，这通常将是您的可订阅模型以及您的可订阅对象订阅的计划实例。一旦检索到模型实例，您可以使用 newSubscription 方法创建模型的订阅。

$subscribable = User::find(1);
$plan = app('wakjoko.subscriptions.plan')->find(1);

$subscribable->newSubscription('main', $plan);

newSubscription 方法的第一个参数应该是订阅的标题。如果您的应用程序提供单个订阅，您可能将其称为 main 或 primary。第二个参数是您的可订阅对象订阅的计划实例。

更改计划

您可以轻松地更改订阅计划，如下所示

$plan = app('wakjoko.subscriptions.plan')->find(2);
$subscription = app('wakjoko.subscriptions.plan_subscription')->find(1);

// Change subscription plan
$subscription->changePlan($plan);

如果两个计划（当前计划和新计划）具有相同的计费频率（例如，invoice_period 和 invoice_interval），则订阅将保留相同的计费日期。如果计划的计费频率不同，则订阅将具有新的计划计费频率，从更改之日开始，并且 订阅使用数据将被清除。此外，如果新计划有试用期并且是新的订阅，则将应用试用期。

功能选项

计划功能对于微调订阅非常有用，您可以多次充值特定功能的使用次数，这样用户就只能使用这么多。功能还具有可重置的能力，因此其使用也可以过期。请看以下示例

// Find plan feature
$feature = app('wakjoko.subscriptions.plan_feature')->where('name', 'listing_duration_days')->first();

// Get feature reset date
$feature->getResetDate(new \Carbon\Carbon());

订阅功能使用

有多种方法可以确定可订阅订阅中特定功能的可用性和使用情况，最常见的方法是 canUseFeature。

canUseFeature 方法根据多个因素返回 true 或 false。

• 功能 已启用。
• 功能值不是 0/false/NULL。
• 或者功能还有剩余的使用次数。

$subscribable->subscription('main')->canUseFeature('listings');

可订阅订阅实例上的其他功能方法有

• getFeatureUsage：返回可订阅使用了特定功能多少次。
• getFeatureRemainings：返回特定功能的可用使用次数。
• getFeatureValue：返回功能值。

所有方法具有相同的签名：例如 $subscribable->subscription('main')->getFeatureUsage('listings');。

记录功能使用情况

为了有效地使用功能方法，您需要跟踪每个功能的每次使用（或至少那些需要跟踪的）。您可以使用通过 subscription() 方法提供的 recordFeatureUsage 方法。

$subscribable->subscription('main')->recordFeatureUsage('listings');

recordFeatureUsage 方法接受 3 个参数：第一个是功能的名称，第二个是要添加的使用次数（默认为 1），第三个指示是否应增量添加（默认行为），当禁用时，使用次数将由提供的数量覆盖。例如：

// Increment by 2
$subscribable->subscription('main')->recordFeatureUsage('listings', 2);

// Override with 9
$subscribable->subscription('main')->recordFeatureUsage('listings', 9, false);

减少功能使用次数

减少功能使用次数几乎与增加相同。这里我们只从实际使用次数中减去一个给定的数量（默认为 1）。

$subscribable->subscription('main')->reduceFeatureUsage('listings', 2);

清除订阅使用数据

$subscribable->subscription('main')->usage()->delete();

检查订阅状态

要使订阅被视为活动状态，以下条件之一必须为 true

• 订阅有一个活动的试用。
• 订阅 ends_at 在未来。

$subscribable->subscribedTo($planId);

或者，您可以使用订阅模型中提供的以下方法

$subscribable->subscription('main')->active();
$subscribable->subscription('main')->canceled();
$subscribable->subscription('main')->ended();
$subscribable->subscription('main')->onTrial();

被取消的订阅，如果有一个活动的试用或 ends_at 在未来，则被视为活动。

续订订阅

要续订订阅，您可以使用订阅模型中提供的 renew 方法。这将根据所选计划设置新的 ends_at 日期，并将清除订阅的使用数据。

$subscribable->subscription('main')->renew();

已经结束期限的被取消订阅无法续订。

取消订阅

要取消订阅，只需在可订阅的订阅上使用 cancel 方法。

$subscribable->subscription('main')->cancel();

默认情况下，订阅将保持活动状态直到期限结束，您可以通过传递 true 立即结束订阅。

$subscribable->subscription('main')->cancel(true);

作用域

订阅模型

// Get subscriptions by plan
$subscriptions = app('wakjoko.subscriptions.plan_subscription')->byPlanId($plan_id)->get();

// Get subscriptions with trial ending in 3 days
$subscriptions = app('wakjoko.subscriptions.plan_subscription')->findEndingTrial(3)->get();

// Get subscriptions with ended trial
$subscriptions = app('wakjoko.subscriptions.plan_subscription')->findEndedTrial()->get();

// Get subscriptions with period ending in 3 days
$subscriptions = app('wakjoko.subscriptions.plan_subscription')->findEndingPeriod(3)->get();

// Get subscriptions with ended period
$subscriptions = app('wakjoko.subscriptions.plan_subscription')->findEndedPeriod()->get();

模型

Wakjoko 订阅 使用 4 个模型

Wakjoko\Subscriptions\Models\Plan;
Wakjoko\Subscriptions\Models\PlanFeature;
Wakjoko\Subscriptions\Models\PlanSubscription;
Wakjoko\Subscriptions\Models\PlanSubscriptionUsage;

更新日志

有关项目的完整历史记录，请参阅 更新日志。

许可证

本软件在 MIT 许可证（MIT） 下发布。