README

为您的Logicalcrow 9.0+应用程序轻松提供定价计划。

主要功能
待办事项
要求
安装
配置文件
模型
事件
使用
变更日志
测试
贡献
安全
鸣谢
许可

主要功能

为您的Logicalcrow 5.4+应用程序轻松提供定价计划。

待办事项

缓存一些选择查询
添加单元测试脚本
制作更好的文档

要求

php >=8.0
Logicalcrow 9.0+

安装

Composer

首先，通过Composer拉取软件包。

$ composer require logicalcrow/pricing-plans

服务提供商

接下来，如果使用Logicalcrow 9.0+，您已完成。如果使用Logicalcrow 9.0，您必须在您的config/app.php文件中包含服务提供商。

// config/app.php

    'providers' => [
        // Other service providers...

        Logicalcrow\PricingPlans\PricingPlansServiceProvider::class,
    ],

配置文件和迁移

使用以下命令发布软件包配置文件和迁移

$ php artisan vendor:publish --provider="Logicalcrow\PricingPlans\PricingPlansServiceProvider"

然后运行迁移

$ php artisan migrate

合同和特质

将Logicalcrow\PricingPlans\Contacts\Subscriber合同和Logicalcrow\PricingPlans\Models\Concerns\Subscribable特质添加到您的订阅者模型中（例如User）。

请参阅以下示例

<?php

namespace App\Models;

use Illuminate\Foundation\Auth\User as Authenticatable;
use Logicalcrow\PricingPlans\Contracts\Subscriber;
use Logicalcrow\PricingPlans\Models\Concerns\Subscribable;

class User extends Authenticatable implements Subscriber
{
    use Subscribable;
    // ...
}

配置文件

您可以配置使用哪些数据库表，使用哪些模型，以及使用哪些正面词汇列表。

定义

正面词汇：用于判断特定功能是否启用。例如，如果功能listing_title_bold的值为Y（Y是正面词汇之一），则表示它已启用。

有关更多详细信息，请参阅config/plans.php配置文件。

模型

PricingPlans使用命名空间Logicalcrow\PricingPlans\Models下的5个模型。您可以通过在配置文件中更改模型类来使用它的扩展类。

功能模型

此模型是功能模型对象

<?php

namespace App\Models;

use Logicalcrow\PricingPlans\Models\Feature as Model;

class Feature extends Model
{
    const FEATURE_UPLOAD_IMAGES = 'upload-images';
    const FEATURE_UPLOAD_VIDEO = 'upload-video';
}

计划模型

此模型是计划模型对象

<?php
namespace App\Models;

use Logicalcrow\PricingPlans\Models\Plan as Model;

class Plan extends Model
{
    const PLAN_FREE = 'free';
    const PLAN_PRO = 'pro';
}

计划功能模型

此模型是计划与功能之间的关联模型对象

计划订阅模型

此模型是计划与订阅者之间的关联模型对象

计划订阅使用模型

此模型是计数功能使用的对象

有关更多详细信息，请参阅每个模型和Logicalcrow\PricingPlans\Models\Concerns\Subscribable特质。

事件

事件位于命名空间Logicalcrow\PricingPlans\Events下。以下是由软件包触发的事件。

`SubscriptionRenewed`事件

当使用renew()方法续订订阅时触发。

`SubscriptionCanceled`事件

当使用cancel()方法取消订阅时触发。

`SubscriptionPlanChanged`事件

当订阅的计划更改时触发。这将触发一次保存PlanSubscription模型。计划更改是通过比较原始值和当前值的plan_id来确定的。

使用

创建功能和计划

<?php

use Logicalcrow\PricingPlans\Models\Feature;
use Logicalcrow\PricingPlans\Models\Plan;

$feature1 = Feature::create([
    'name' => 'Upload images',
    'code' => 'upload-images',
    'description' => null,
    'interval_unit' => 'day',
    'interval_count' => 1,
    'sort_order' => 1,
]);

$feature2 = Feature::create([
    'name' => 'upload video',
    'code' => 'upload-video',
    'description' => null,
    'interval_unit' => 'day',
    'interval_count' => 1,
    'sort_order' => 2,
]);

$plan = Plan::create([
    'name' => 'Pro',
    'code' => 'pro',
    'description' => 'Pro plan',
    'price' => 9.99,
    'interval_unit' => 'month',
    'interval_count' => 1,
    'trial_period_days' => 5,
    'sort_order' => 1,
]);

$plan->features()->attach([
    $feature1->id => ['value' => 5, 'note' => 'Can upload maximum 5 images daily'],
    $feature2->id => ['value' => 1, 'note' => 'Can upload maximum 1 video daily'],
]);

创建订阅

您可以使用Subscribable特质中的newSubscription()函数订阅用户到计划。首先，检索您的订阅者模型实例，通常是用户模型和用户订阅的计划实例。检索模型实例后，您可以使用newSubscription方法创建模型订阅。

<?php

use Illuminate\Support\Facades\Auth;
use Logicalcrow\PricingPlans\Models\Plan;

$user = Auth::user();
$plan = Plan::code(Plan::PLAN_PRO)->firstOrFail();

$user->newSubscription('main', $plan)->create();

将订阅名称作为第一个参数传递给 newSubscription 方法。如果您的应用程序仅提供一个订阅，您可能将其称为 main 或 primary。第二个参数是用户订阅的计划实例。

订阅能力

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

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

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

$user->subscription('main')->ability()->canUse(Feature::FEATURE_UPLOAD_IMAGES);

其他方法包括：

enabled：当功能值的配置文件中列出时，返回 true。
consumed：返回用户使用特定功能的次数。
remainings：返回特定功能的可用使用次数。
value：返回功能值。

所有方法具有相同的签名，例如：
$user->subscription('main')->ability()->consumed(Feature::FEATURE_UPLOAD_IMAGES);.

记录功能使用

为了有效地使用能力方法，您需要跟踪每个功能的每次使用（或者至少是那些需要跟踪的）。您可以使用通过用户 subscriptionUsage 方法提供的 record 方法。

$user->subscriptionUsage('main')->record(Feature::FEATURE_UPLOAD_IMAGES);

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

// Increment by 2
$user->subscriptionUsage('main')->record(Feature::FEATURE_UPLOAD_IMAGES, 2);

// Override with 9
$user->subscriptionUsage('main')->record(Feature::FEATURE_UPLOAD_IMAGES, 9, false);

减少功能使用

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

$user->subscriptionUsage('main')->reduce(Feature::FEATURE_UPLOAD_IMAGES, 2);

清除订阅使用数据

$user->subscriptionUsage('main')->clear();

检查订阅状态

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

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

$user->subscribed('main');
$user->subscribed('main', $planId); // Check if user is using a particular plan

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

$user->subscription('main')->isActive();
$user->subscription('main')->isCanceled();
$user->subscription('main')->isCanceledImmediately();
$user->subscription('main')->isEnded();
$user->subscription('main')->onTrial();

具有活动的试用期或 ends_at 在未来的已取消订阅被视为活动状态。

续订订阅

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

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

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

取消订阅

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

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

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

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

作用域

订阅模型

<?php

use Logicalcrow\PricingPlans\Models\PlanSubscription;

// Get subscriptions by plan:
$subscriptions = PlanSubscription::byPlan($plan_id)->get();

// Get subscription by subscriber:
$subscription = PlanSubscription::bySubscriber($user)->first();

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

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

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

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

变更日志

查看所有更改日志，请参阅 CHANGELOG

测试

$ git clone git@github.com/oanhnn/Logicalcrow-pricing-plans.git /path
$ cd /path
$ composer install
$ composer phpunit

贡献

有关详细信息，请参阅 CONTRIBUTING。

安全

如果您发现任何与安全相关的问题，请通过电子邮件发送给 Oanh Nguyen 而不是使用问题跟踪器。

鸣谢

我在 2017 年中旬从 gerardojbaez/laraplans 项目中分叉并重新创建了此项目。感谢 Gerardo Baez。

logicalcrow / pricing-plans

维护者

详细信息