README

Easy provide pricing plans for Your Laravel 8.+ Application.

Main features
TODO
Requirements
Installation
Config File
Models
Events
Usage
Changelog
Testing
Contributing
Security
Credits
License

Main features

Easy provide pricing plans for Your Laravel 8.+ Application.

TODO

Caching some select query
Add unit test scripts
Make better documents

Requirements

php >=7.3
Laravel 8.+

Installation

Composer

Begin by pulling in the package through Composer.

$ composer require cityhunter/laravel-pricing-plans

Service Provider

Next, if using Laravel 8.+, you done. If using Laravel 5.4, you must include the service provider within your config/app.php file.

// config/app.php

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

        Laravel\PricingPlans\PricingPlansServiceProvider::class,
    ],

Config file and Migrations

Publish package config file and migrations with the command:

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

Then run migrations:

$ php artisan migrate

Contract and Traits

Add Laravel\PricingPlans\Contacts\Subscriber contract and Laravel\PricingPlans\Models\Concerns\Subscribable trait to your subscriber model (Eg. User).

See the following example:

<?php

namespace App\Models;

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

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

Config File

You can configure what database tables, what models to use, list of positive words will use.

Definitions:

Positive Words: Are used to tell if a particular feature is enabled. E.g., if the feature listing_title_bold has the value Y (Y is one of the positive words) then, that means it's enabled.

Take a look to the config/plans.php config file for more details.

Models

PricingPlans uses 7 models under namespace Laravel\PricingPlans\Models. You can change to using extended classes of it by changing models class in config file:

Feature model

This model is model object of feature

<?php

namespace App\Models;

use Laravel\PricingPlans\Models\Feature as Model;

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

Plan model

This model is model object of plan

<?php
namespace App\Models;

use Laravel\PricingPlans\Models\Plan as Model;

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

Group model

This model is model object of group

<?php
namespace App\Models;

use Laravel\PricingPlans\Models\Group as Model;

class Group extends Model
{
   
}

PlanFeature model

This model is relation model object between plan and feature

PlanGroup model

This model is relation model object between plan and group

PlanSubscription model

This model is relation model object between plan and subscriber

PlanSubscriptionUsage model

This model is object for counting usage feature

For more details take a look to each model and the Laravel\PricingPlans\Models\Concerns\Subscribable trait.

Events

Events are under the namespace Laravel\PricingPlans\Events. The following are the events triggered by the package.

`SubscriptionRenewed` event

Fired when a subscription is renewed using the renew() method.

`SubscriptionCanceled` event

Fired when a subscription is canceled using the cancel() method.

`SubscriptionPlanChanged` event

Fired when a subscription's plan is changed. This will be triggered once the PlanSubscription model is saved. Plan change is determine by comparing the original and current value of plan_id.

Usage

Create features and plan

<?php

use Laravel\PricingPlans\Models\Feature;
use Laravel\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'],
]);

Create a group of plans

<?php

use Laravel\PricingPlans\Models\Group;
use Laravel\PricingPlans\Models\Plan;

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

$plan2 = Plan::create([
    'name' => 'Free',
    'code' => 'Free',
    'description' => 'Free plan',
    'price' => 0,
    'interval_unit' => 'month',
    'interval_count' => 1,
    'trial_period_days' => 30,
    'sort_order' => 1,
]);

$group = Group::create([
    'name' => 'Service1',
    'description' => "Service 1 plan group description"
]);

$group->plans()->attach([
    $plan1->id => ['created_at' => now()],
    $plan2->id => ['created_at' => now()],
]);

Creating subscriptions

You can subscribe a user to a plan by using the newSubscription() function available in the Subscribable trait. First, retrieve an instance of your subscriber model, which typically will be your user model and an instance of the plan your user is subscribing to. Once you have retrieved the model instance, you may use the newSubscription method to create the model's subscription.

<?php

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

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

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

The first argument passed to newSubscription method should be the name of the subscription. If your application offer a single subscription, you might call this main or primary. The second argument is the plan instance your user is subscribing to.

Subscription Ability

There's multiple ways to determine the usage and ability of a particular feature in the user subscription, the most common one is canUse:

The canUse method returns true or false depending on multiple factors:

Feature is enabled.
Feature value isn't 0.
Or feature has remaining uses available.

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

Other methods are:

enabled: returns true when the value of the feature is a positive word listed in the config file.
consumed: returns how many times the user has used a particular feature.
remainings: returns available uses for a particular feature.
value: returns the feature value.

All methods share the same signature: e.g.
$user->subscription('main')->ability()->consumed(Feature::FEATURE_UPLOAD_IMAGES);.

Record Feature Usage

In order to efectively use the ability methods you will need to keep track of every usage of each feature (or at least those that require it). You may use the record method available through the user subscriptionUsage() method:

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

The record method accept 3 parameters: the first one is the feature's code, the second one is the quantity of uses to add (default is 1), and the third one indicates if the addition should be incremental (default behavior), when disabled the usage will be override by the quantity provided. E.g.:

// 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);

Reduce Feature Usage

Reducing the feature usage is almost the same as incrementing it. Here we only substract a given quantity (default is 1) to the actual usage:

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

Clear The Subscription Usage Data

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

Check Subscription Status

For a subscription to be considered active one of the following must be true:

Subscription has an active trial.
Subscription ends_at is in the future.

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

Alternatively you can use the following methods available in the subscription model:

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

Canceled subscriptions with an active trial or ends_at in the future are considered active.

Renew a Subscription

To renew a subscription you may use the renew method available in the subscription model. This will set a new ends_at date based on the selected plan and will clear the usage data of the subscription.

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

Change a Subscription

To change a subscription you may use the changePlan method available in the subscription model. This will set a new ends_at date, set a new plan id based on the selected plan and will clear the usage data of the subscription.

$user->subscription('main')->changePlan($plan);

Canceled subscriptions with an ended period can't be renewed.

Cancel a Subscription

To cancel a subscription, simply use the cancel method on the user's subscription:

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

By default the subscription will remain active until the end of the period, you may pass true to end the subscription immediately:

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

Scopes

Subscription Model

<?php

use Laravel\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

See all change logs in CHANGELOG

Testing

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

Contributing

Please see CONTRIBUTING for details.

Security

Use the issue tracker.

Credits

I forked and recreated this project from henoc35/laravel-pricing-plans project in late-2021. Thanks Djabia Henoc

olubunmitosin / laravel-pricing-plans

Maintainers

Details