README

SaaS style recurring plans for Laravel 5.

Please note: this package doesn't handle payments.

Considerations
Installation
Usage
Models
Config File

Considerations

Payments are out of scope for this package.
You may want to extend all of LaraPlans models since it's likely that you will need to override the logic behind some helper methods like renew(), cancel() etc. E.g.: when cancelling a subscription you may want to also cancel the recurring payment attached.

Installation

Composer

Add the following to your composer.json file:

{
    "require": {
        "siqwell/laraplans": "0.*"
    }
}

And then run in your terminal:

composer install

Service Provider

Add Siqwell\LaraPlans\LaraPlansServiceProvider::class to your application service providers in config/app.php file:

'providers' => [
    /**
     * Third Party Service Providers...
     */
    Siqwell\LaraPlans\LaraPlansServiceProvider::class,
]

Config file and Migrations

Publish package config file and migrations with the command:

php artisan vendor:publish --provider="Siqwell\LaraPlans\LaraPlansServiceProvider"

Then run migrations:

php artisan migrate

Traits and Contracts

Add Siqwell\LaraPlans\Traits\PlanSubscriber trait and Siqwell\LaraPlans\Contracts\PlanSubscriberInterface contract to your User model.

See the following example:

<?php

namespace App\Models;

use Illuminate\Foundation\Auth\User as Authenticatable;
use Siqwell\LaraPlans\Contracts\PlanSubscriberInterface;
use Siqwell\LaraPlans\Traits\PlanSubscriber;

class User extends Authenticatable implements PlanSubscriberInterface
{
    use PlanSubscriber;

Usage

Create a Plan

<?php

use Siqwell\LaraPlans\Models\Plan;
use Siqwell\LaraPlans\Models\PlanFeature;

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

$plan->features()->saveMany([
    new PlanFeature(['code' => 'listings', 'value' => 50, 'sort_order' => 1]),
    new PlanFeature(['code' => 'pictures_per_listing', 'value' => 10, 'sort_order' => 5]),
    new PlanFeature(['code' => 'listing_duration_days', 'value' => 30, 'sort_order' => 10]),
    new PlanFeature(['code' => 'listing_title_bold', 'value' => 'Y', 'sort_order' => 15])
]);

Creating subscriptions

You can subscribe a user to a plan by using the newSubscription() function available in the PlanSubscriber 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 Auth;
use Siqwell\LaraPlans\Models\Plan;

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

$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('listings');

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('listings');.

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('listings');

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('listings', 2);

// Override with 9
$user->subscriptionUsage('main')->record('listings', 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('listings', 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')->active();
$user->subscription('main')->canceled();
$user->subscription('main')->ended();
$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();

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 Siqwell\LaraPlans\Models\PlanSubscription;

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

// Get subscription by user:
$subscription = PlanSubscription::byUser($user_id)->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();

Models

LaraPlans uses 4 models:

Siqwell\LaraPlans\Models\Plan;
Siqwell\LaraPlans\Models\PlanFeature;
Siqwell\LaraPlans\Models\PlanSubscription;
Siqwell\LaraPlans\Models\PlanSubscriptionUsage;

For more details take a look to each model and the Siqwell\LaraPlans\Traits\PlanSubscriber trait.

Config File

You can configure what models to use, list of positive words and the list of features your app and your plans 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.
Features: List of features that your app and plans will use.

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

siqwell / laraplans

Maintainers

Details