README

This is a simple to use subscription package for Laravel.

It is heavvly inspired by the renvex/laravel-subscriptions package, just simpler and working :)

Sorry, My point is that the renvex packages seems to be abandond.

Payments

Payment support is in the works, so stay tuned.
We will most likley use laraveldaily/laravel-invoices and then a payment package

Installation

You can install the package via composer:

composer require rabol/laravel-simple-subscription

You can publish and run the migrations with:

php artisan vendor:publish --provider="Rabol\SimpleSubscription\SimpleSubscriptionServiceProvider" --tag="laravel-simple-subscription-migrations"
php artisan migrate

You can publish the config file with:

php artisan vendor:publish --provider="Rabol\SimpleSubscription\SimpleSubscriptionServiceProvider" --tag="laravel-simple-subscription-config"

This is the contents of the published config file:

return [
];

Usage

Add Subscriptions to your model

For the sake of simplicity there is a trait that can be added to any model.

The most common use case is to add Subscription functionality to your User model just use the Rabol\SimpleSubscription\Traits\HasSubscriptions trait like this:

namespace App\Models;

use Rabol\SimpleSubscription\Traits\HasSubscriptions;
use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable
{
    use HasSubscriptions;
}

That's it, now you can use subscriptions on your user model only have to use that trait in our User model! Now your users may subscribe to plans.

Create a new Plan

$newPlan = SimpleSubscriptionPlan::create([
    'name' => 'My cool subscription',
    'description' => 'This is a very cool plan',
    'is_active' => true,
    'price' => 12.50,
    'signup_fee' => 0,
    'currency' => 'eur',
    'trial_period'  => 1,
    'trial_interval' => 'week',
    'invoice_period' => 1,
    'invoice_interval' => 'month',
    'grace_period' => 3,
    'grace_interval' => 'day',
]);

Add a feature

$planFeature = $newPlan
    ->features()
    ->create([
        'name' => 'My cool feature',
        'description' => 'This is my cool feature',
        'value' => 100,
        'resettable_period' => 2,
        'resettable_interval' => 'month',
        'sort_order' => 1,
    ]);

Subscription plan details

$plan = SimpleSubscriptionPlan::find(1);
or
$plan = SimpleSubscriptionPlan::whereName('My cool subscription')->first();

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

Get Feature Value

There are different ways to get information about a feature on a plan To get the value of the feature 'My cool feature'.:

// Use the plan instance to get feature's value
$myCoolFeatureValue = $plan->getFeatureByName('My Cool feature')->value;

Get feature usage

// Get the usage of the feature you can
$myCoolFeatureUsage = SimpleSubscriptionPlanFeature::wherePlanId(1)->whereName('Feature 1')->first()->usage()->first()->used;

Create a Subscription

You can subscribe a user to a plan by using the newSubscription() function available in the HasSubscriptions 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.

$user = User::find(1);
$plan = SimpleSubscriptionPlan::whereName('My cool subscription')->first();

$user->newSubscription($plan);

you can also specify the start date like this:

$user = User::find(1);
$plan = SimpleSubscriptionPlan::whereName('My cool subscription')->first();

$user->newSubscription($plan, Carbon::today());

If no start date is specified, the subscription will start today. The end date is calculated from the settings on the plan.

Change the Plan

To change the plan do this:

$newPlan = SimpleSubscriptionPlan::whereName('My second cool plan')->first();
$subscription = SimpleSubscriptionPlanSubscription::whereName('My cool subscription')->first();

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

If both plans (current and new plan) have the same billing frequency (e.g., invoice_period and invoice_interval) the subscription will retain the same billing dates. If the plans don't have the same billing frequency, the subscription will have the new plan billing frequency, starting on the day of the change and the subscription usage data will be cleared. Also, if the new plan has a trial period, and it's a new subscription, the trial period will be applied.

Subscription Feature Usage

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

The canUseFeature 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('My cool subscription')->canUseFeature('My cool feature');

Other feature methods on the user subscription instance are:

getFeatureUsage: returns how many times the user has used a particular feature.
getFeatureRemaining: returns available uses for a particular feature.
getFeatureValue: returns the feature value.

All methods share the same signature: e.g. $user->subscription('My cool subscription')->getFeatureUsage('My cool feature');.

Record Feature Usage

In order to effectively 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 recordFeatureUsage method available through the user subscription() method:

$user->subscription('My cool subscription')->recordFeatureUsage('My cool feature');

The recordFeatureUsage method accept 3 parameters: the first one is the feature's name, 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->subscription('My cool subscription')->recordFeatureUsage('My cool feature', 2);

// Override with 9
$user->subscription('My cool subscription')->recordFeatureUsage('My cool feature', 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: The difference from the recordFeatureUsage method is that the reduceFeatureUsage will not look at reset date

$user->subscription('My cool subscription')->reduceFeatureUsage('My cool feature', 2);

Increase Feature Usage

Increasing the feature usage is almost the same as recordFeatureUsage. this function simply add a given quantity to the value:

One more difference from the recordFeatureUsage method is that the increaseFeatureUsage will not look at reset date

$user->subscription('My cool subscription')->increaseFeatureUsage('My cool feature', 2);

Clear The Subscription Usage Data

$user->subscription('My cool subscription')->usage()->delete();

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->subscribedToPlanId($planId);
or
$user->subscribedToPlanName('My cool plan');

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

$user->subscription('My cool subscription')->active();
$user->subscription('My cool subscription')->canceled();
$user->subscription('My cool subscription')->ended();
$user->subscription('My cool subscription')->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('My cool subscription')->renew();

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('My cool subscription')->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('My cool subscription')->cancel(true);

Scopes

Subscription Model

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

// Get bookings of the given user
$user = \App\Models\User::find(1);
$bookingsOfUser = SimpleSubscriptionPlanSubscription::ofSubscriber($user)->get();

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

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

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

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

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

The MIT License (MIT). Please see License File for more information.

rabol / laravel-simple-subscription

Maintainers

Details