README

模块订阅 是一个灵活的计划和订阅管理系统，适用于模块，具有运行您的SAAS服务的所需工具，以高效的方式。它简单而强大的架构，为您的业务提供了一个坚实的平台。

注意事项

本软件包不涉及支付。
您可能需要扩展一些核心模型，以便覆盖某些辅助方法（如 renew()、cancel() 等）背后的逻辑。例如：在取消订阅时，您可能还想取消附加的周期性支付。

安装

使用composer安装软件包
```
composer require turahe/subscription
```

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

php artisan vendor:publish --provider="Turahe\Subscription\SubscriptionServiceProvider"

通过以下命令执行迁移
```
php artisan migrate
```
完成！

用法

将订阅添加到用户模型

模块订阅 特别为Eloquent设计，并在任何其他模块相关方面都非常注重简洁性。要将订阅功能添加到您的用户模型，只需使用如下所示的 \Rinvex\Subscriptions\Traits\HasPlanSubscriptions 特性

namespace App\Models;

use Turahe\Subscription\Traits\HasPlanSubscriptions;
use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable
{
    use HasPlanSubscriptions;
}

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

注意：您可以在任何订阅者模型上使用 HasPlanSubscriptions 特性，它不必是用户模型，实际上任何模型都可以。

创建计划

use Turahe\Subscription\Models\Plan;
use Turahe\Subscription\Models\Feature;
use Turahe\Subscription\Interval;

$plan = Plan::create([
    'name' => 'Pro',
    'description' => 'Pro plan',
    'price' => 9.99,
    'signup_fee' => 1.99,
    'invoice_period' => 1,
    'invoice_interval' => Interval::MONTH->value,
    'trial_period' => 15,
    'trial_interval' => Interval::DAY->value,
    'sort_order' => 1,
    'currency' => 'USD',
]);

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

获取计划详情

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

use Turahe\Subscription\Models\Plan;

$plan = 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();

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

获取功能值

假设您想显示上面提到的 pictures_per_listing 功能的值。您可以通过多种方式完成此操作

use Turahe\Subscription\Models\Feature;
use Turahe\Subscription\Models\Subscription;

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

// Query the feature itself directly
$amountOfPictures = Feature::where('slug', 'pictures_per_listing')->first()->value;

// Get feature value through the subscription instance
$amountOfPictures = Subscription::find(1)->getFeatureValue('pictures_per_listing');

创建订阅

您可以使用 HasPlanSubscriptions 特性中的 newSubscription() 函数订阅用户到计划。首先，检索您的订阅者模型实例，通常是您的用户模型以及用户要订阅的计划实例。一旦检索到模型实例，您可以使用 newSubscription 方法创建模型的订阅。

use Turahe\Auth\Models\User;use Turahe\Subscription\Models\Plan;

$user = User::find(1);
$plan = Plan::find(1);

$user->newPlanSubscription('main', $plan);

传递给 newSubscription 方法的第一个参数应该是订阅的标题。如果您的应用程序提供单个订阅，您可以将其称为 main 或 primary，而第二个参数是用户订阅的计划实例，还有一个可选的第三个参数可以指定自定义的起始日期，作为 Carbon\Carbon 的实例（如果没有提供，则默认为现在）。

更改计划

您可以轻松地按照以下方式更改订阅计划

use Turahe\Subscription\Models\Plan;
use Turahe\Subscription\Models\Subscription;

$plan = Plan::find(2);
$subscription = Subscription::find(1);

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

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

功能选项

计划功能非常适合微调订阅，您可以多次使用某个功能，因此用户可能只使用这么多。功能还具有可重置的能力，因此其使用也可能过期。以下是一些示例

use Turahe\Subscription\Models\Feature;

// Find plan feature
$feature = Feature::where('name', 'listing_duration_days')->first();

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

订阅功能使用

有多种方法可以确定用户订阅中特定功能的使用和权限，最常见的是canUseFeature

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

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

$user->planSubscription('main')->canUseFeature('listings');

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

getFeatureUsage：返回用户使用特定功能的次数。
getFeatureRemainings：返回特定功能的可用使用次数。
getFeatureValue：返回功能值。

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

记录功能使用

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

$user->planSubscription('main')->recordFeatureUsage('listings');

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

// Increment by 2
$user->planSubscription('main')->recordFeatureUsage('listings', 2);

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

减少功能使用

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

$user->planSubscription('main')->reduceFeatureUsage('listings', 2);

清除订阅使用数据

$user->planSubscription('main')->usage()->delete();

检查订阅状态

要使订阅被视为活跃的，以下其中之一必须为true

订阅有一个活跃的试用期。
订阅的ends_at日期在将来。

$user->subscribedTo($planId);

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

$user->planSubscription('main')->active();
$user->planSubscription('main')->canceled();
$user->planSubscription('main')->ended();
$user->planSubscription('main')->onTrial();

具有活跃试用期或ends_at日期在将来的已取消订阅被视为活跃。

续订订阅

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

$user->planSubscription('main')->renew();

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

取消订阅

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

$user->planSubscription('main')->cancel();

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

$user->planSubscription('main')->cancel(true);

作用域

订阅模型

use Turahe\Auth\Models\User;use Turahe\Subscription\Models\Subscription;

// Get subscriptions by plan
$subscriptions = Subscription::byPlanId($plan_id)->get();

// Get bookings of the given user
$user = User::find(1);
$bookingsOfSubscriber = Subscription::ofSubscriber($user)->get();

// Get subscriptions with trial ending in 3 days
$subscriptions = Subscription::findEndingTrial(3)->get();

// Get subscriptions with ended trial
$subscriptions = Subscription::findEndedTrial()->get();

// Get subscriptions with period ending in 3 days
$subscriptions = Subscription::findEndingPeriod(3)->get();

// Get subscriptions with ended period
$subscriptions = Subscription::findEndedPeriod()->get();

模型

模块订阅使用4个模型

Turahe\Subscription\Models\Plan;
Turahe\Subscription\Models\Feature;
Turahe\Subscription\Models\Subscription;
Turahe\Subscription\Models\SubscriptionUsage;

turahe / subscription

维护者

详细信息