Laraplans

SaaS style recurring plans for Laravel 5.

Payments are out of scope for this package at this moment, but suggestions are welcome!

Table of Content

• Feedback
• How to install
  • Composer
  • Service Provider
  • Config file and Migrations
  • Traits and Contracts
• Usage
  • Create a Plan
  • Get the value of Feature
  • Creating subscriptions
  • Subscription Ability
  • Record Feature Usage
  • Reduce Feature Usage
  • Clear The Subscription Usage Data
  • Check Subscription Status
  • Renew a Subscription
  • Cancel a Subscription
  • Scopes
• Events
  • SubscriptionCreated
  • SubscriptionRenewed
  • SubscriptionCanceled
  • SubscriptionPlanChanged
• Models
• Config File

Feedback

Feel free to leave your feedback!

How to install

Composer

Add the following to your composer.json file:

"require": {
    "gerardojbaez/laraplans": "~2.0"
}

And then run in your terminal:

composer install

Quick Installation

Above installation can also be simplified by using the following command:

composer require gerardojbaez/laraplans

Service Provider

Add Gerardojbaez\Laraplans\LaraplansServiceProvider::class to your application service providers in config/app.php file:

'providers' => [
    /**
     * Third Party Service Providers...
     */
    Gerardojbaez\Laraplans\LaraplansServiceProvider::class,
]

Config file and Migrations

Publish package config file and migrations with the following command:

php artisan vendor:publish --provider="Gerardojbaez\Laraplans\LaraplansServiceProvider"

Then run migrations:

php artisan migrate

Traits and Contracts

Add Gerardojbaez\Laraplans\Traits\PlanSubscriber trait and Gerardojbaez\Laraplans\Contracts\PlanSubscriberInterface contract to your User model.

See the following example:

<?php

namespace App\Models;

use Illuminate\Foundation\Auth\User as Authenticatable;
use Gerardojbaez\Laraplans\Contracts\PlanSubscriberInterface;
use Gerardojbaez\Laraplans\Traits\PlanSubscriber;

class User extends Authenticatable implements PlanSubscriberInterface
{
    use PlanSubscriber;

Usage

Create a Plan

<?php

use Gerardojbaez\Laraplans\Models\Plan;
use Gerardojbaez\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])
]);

Get the value of Feature

Say you want to show the value of the feature pictures_per_listing from above. You can use getFeatureByCode().

$amountOfPictures = $plan->getFeatureByCode('pictures_per_listing')->value

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 Gerardojbaez\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')->canceledImmediately();
$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 Gerardojbaez\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();

Events

Events are under the namespace Gerardojbaez\Laraplans\Events. The following are the events triggered by the package.

SubscriptionCreated

Fired when a subscription is created.

SubscriptionRenewed

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

SubscriptionCanceled

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

SubscriptionPlanChanged

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.

Models

Laraplans uses 4 models:

Gerardojbaez\Laraplans\Models\Plan;
Gerardojbaez\Laraplans\Models\PlanFeature;
Gerardojbaez\Laraplans\Models\PlanSubscription;
Gerardojbaez\Laraplans\Models\PlanSubscriptionUsage;

For more details take a look to each model and the Gerardojbaez\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.