#125

Product support

Get help in the plugin support forum.

Categories

  • Developer Tools
  • Miscellaneous
  • Social
  • Utility

The plugin extends Cumulus core. It makes your application ready for managing clusters' subscriptions for plans.

This plugin makes Cumulus environment complete.

If you do not know what Cumulus is, then click here.

These plugin(s) are required for the plugin:

Active trial subscription which ends on 18/10/2018. Will be changed to Free then.

Installation note

After installation, your current plans will become no-expiring, no-paid ones (explanation below). What is more, the option to change plan of cluster in backend will be disabled.

After installing the plugin, every existing cluster will get no-expiring subscription to plan that it had before installation. So functionally you and your users will not see any differences. The only difference will be managing your clusters' plans which right now will be possible only by adding and updating subscriptions.

Set up the scheduler

You have to configure scheduler for SubcscriptionsOperator to be able to process expired subscriptions (more info about setting up the scheduler here).

Key notes (good to understand before using)

  1. Cluster can have only one subscription and one subscription can refer to only one cluster.
  2. While creating subscriptions and renewing them using subscriptionRepository you do not have to enter plan after expiry and ending date because they are filled automatically based on selected plan.
  3. If you want to update subscription using backend then you will have to enter plan after expiry and ending date manually.
  4. Deleting subscription will not change cluster's plan (so you better do not delete subscriptions)
  5. The plugin will add functionality to inform application if plans are expiring or paid.
    • By paid plan I mean plan that has to be paid to get cluster assigned to plan (this has to be handled by your application).
    • By expiring plan I mean plan that when assigned to a cluster will expire one day and will have to be changed to a different plan (see 'Example usage' section below for better understanding).
  6. You have to write your own payment handlers and managing subscriptions (if you want them to manage automatically). The plugin does not have payments gateways and integrations.
  7. Good idea is to have a lot of different plans to toggle between (example below).

How-to

Managing switching of plans

You can create a lot of combinations of plans. Every plan has "plan after expiry" property, which means you can set every config you want to get using plans in such way.

If you want you may event toggle two plans every week if you set so. I does not make sense, but you can :). Just set one week expiry period for both, and "plan after expiry" to each other.

Maybe in your environment it makes sense to create "Trial" and "After trial" plans.

Or maybe "Bronze", "Silver", "Gold" and "Not paid". In this case "Not paid" will not have any paid features assigned to it. This way cluster which has not paid, will lose access to the paid features.

Example usage

Let's assume we want to have configuration that supports 14 days Trial plan that:

  • changes to Free plan if a cluster has not paid and
  • changes to Full plan if cluster has paid.

In order to manage this use case using CumulusSubscriptions plugin you have to do as follows.

Create three plans:

  1. Free, which does not expire and is not paid
  2. Trial, which expires after 14 days, is not paid and switches to Free automatically after that period
  3. Full, which expires after (for example) one year, is paid and switches automatically to Free after that period

Let's say we have user John that wants to register his company's (ACME Corp.) account in our service.

By default you have to create new subscription just after creating account for him. If you use ClusterRepository->addClusterToPlan method than your code in init.php may look like this:

use Initbiz\CumulusSubscriptions\Repositories\SubscriptionRepository;
...
Event::listen('initbiz.cumuluscore.addClusterToPlan', function ($cluster, $plan) {
    $subscriptionRepository = new SubscriptionRepository();
    $subscriptionRepository->newSubscription($cluster->slug, $plan->slug);
});

By default newSubscription method use config set in plan, so we do not have to enter any other details to create subscription (of course you can override default config by adding third parameter with key => value array, see below).

If you have configured the plan properly, than Acme Corp. should now have Trial plan that expires in 14 days. After expiration subscriptionsOperator will change its plan to Free.

If John pays during those 14 days we have two options.

  1. Change his "plan after expiry" to Full manually, by going to backend -> subscriptions and edit ACME Corp.'s subscription,
  2. Automate this process using subscriptionsRepository in your payment-successful handler.

In some environments we have to manage subscriptions manually, so the first option makes sense (for example client paid us earlier, by cash, check or any other not-automatic way).

But in a lot of cases payments will be processed automatically so we can use the second option. After payment is considered successful (transaction saved, amount matches the plan price and payment service confirms status) we can use setPlanAfterExpiry() method. For example:

use Initbiz\CumulusSubscriptions\Repositories\SubscriptionRepository;
...
$clusterSlug = "acme-corp";
$planSlug = "full";

if ($paymentSuccessful) {
    $subscriptionRepository = new SubscriptionRepository();
    $subscriptionRepository->setPlanAfterExpiry($clusterSlug, $planSlug);
}
...

This way SubscriptionsOperator, after Trial expires, will automatically change the plan to Full. Expiring date will be calculated from current date and config of plan.

Instead of setPlanAfterExpiry() you may want to use overrideCurrentPlan() which works similar, but changes the plan at time of running without waiting for previous plan to expire. The method works in such a way that if previous plan was expiring and new plan is expiring as well than those two dates will sum up. It works well if our user still has for example 2 months of current plan and we want to give him another 12.

If you want to change the current plan without adding dates you can use third parameter to this method (see below).

What is more, you still can use typical update method:

use Initbiz\CumulusSubscriptions\Repositories\SubscriptionRepository;
...
$subscriptionRepository = new SubscriptionRepository();
$clusterSlug = "acme-corp";
$subscription = $this->getSubscription($clusterSlug);

$data = [
    'cluster_slug' => $clusterSlug,
    'plan_id' => $plan->plan_id,
    'is_expiring' => false,
    'plan_id_after_expiry' => $plan2->plan_id,
    'starts_at' => Carbon::now(),
    'updated_at' => Carbon::now(),
    'comment' => "",
];

$subscriptionRepository->update($data, $clusterSlug);
...

subscriptionsOperator class

subscriptionsOperator is a class that will manage current subscriptions. If you have set up scheduler, the SubscriptionsOperator will run daily at 1:00 processExpiredSubscriptions() method. The method sets plan to "plan after expiry" definition for every expired subscription.

subscriptionsRepository class

prolongateSubscriptionTo(string $clusterSlug, string $date)

Prolongates subscription of given cluster till $date date.

prolongateSubscription(string $clusterSlug, int $expiringCount, string $expiringPeriod)

Prolongates subscription from subscription ends_at till ends_at plus $expiringCount $expiringPeriods (for example prolongate for 3 days, 2 weeks, 1 year and so on).

prolongatePlanSubscription(string $clusterSlug, string $planSlug)

Prolongates the subscription till current subscription ends_at + default plan period.

newSubscription(string $clusterSlug, string $planSlug, array $options = [])

The method will not run if any subscription for the cluster already exists.

It creates new subscription based on config in plan defined by $planSlug. Using the third parameter you can override defaults set in plan.

overrideCurrentPlan(string $clusterSlug, string $planSlug, bool $sumDates)

Override the current cluster's plan to the one specified in $planSlug. If $sumDates is set to false, the method will not add dates from current subscription ending and the one specified and just starts from now.

setPlanAfterExpiry(string $clusterSlug, string $planSlug)

Change plan_after_expiry to the one specified in $planSlug.

When the subscription expires the plan will be automatically changed this plan by SubscriptionsOperator.

Future plans

  • Notify admin about endings of subscriptions
  • Notify users about ending of their subscription
  • Component with "days-to-end" notification
  • Get time of running scheduler from config
  • Import/export of subscriptions
  • Deactivating subscriptions
1.0.1

Initialize plugin.

Oct 09, 2018