Download the PHP package keoby/laravel-plans without Composer

Laravel Plans

Laravel Plans is a package for SaaS apps that need management over plans, features, subscriptions, events for plans or limited, countable features.

Laravel Cashier

While Laravel Cashier does this job really well, there are some features that can be useful for SaaS apps:

• Countable, limited features - If you plan to limit the amount of resources a subscriber can have and track the usage, this package does that for you.
• Event-driven by nature - you can listen for events. What if you can give 3 free days to the next subscription if your users pay their invoice in time?

Installation

Install the package:

If your Laravel version does not support package discovery, add this line in the providers array in your config/app.php file:

Publish the config file & migration files:

Migrate the database:

Add the HasPlans trait to your Eloquent model:

Creating plans

The basic unit of the subscription-like system is a plan. You can create it using Keoby\LaravelPlans\Models\Plan or your model, if you have implemented your own.

Features

Each plan has features. They can be either countable, and those are limited or unlimited, or there just to store the information, such a specific permission.

Marking a feature type can be done using:

• feature, is a single string, that do not needs counting. For example, you can store permissions.
• limit, is a number. For this kind of feature, the limit attribute will be filled. It is meant to measure how many of that feature the user has consumed, from this subscription. For example, you can count how many build minutes this user has consumed during the month (or during the Cycle, which is 30 days in this example)

Note: For unlimited feature, the limit field will be set to any negative value.

To attach features to your plan, you can use the relationship features() and pass as many Keoby\LaravelPlans\Models\Featureinstances as you need:

Later, you can retrieve the permissions directly from the subscription:

Subscribing to plans

Your users can be subscribed to plans for a certain amount of days or until a certain date.

By default, the plan is marked as recurring, so it's eligible to be extended after it expires, if you plan to do so like it's explained in the Recurrency section below.

If you don't want a recurrent subscription, you can pass false as a third argument:

If you plan to subscribe your users until a certain date, you can pass strngs containing a date, a datetime or a Carbon instance.

If your subscription is recurrent, the amount of days for a recurrency cycle is the difference between the expiring date and the current date.

Note: If the user is already subscribed, the subscribeTo() will return false. To avoid this, upgrade or extend the subscription.

Upgrading subscription

Upgrading the current subscription's plan can be done in two ways: it either extends the current subscription with the amount of days passed or creates another one, in extension to this current one.

Either way, you have to pass a boolean as the third parameter. By default, it extends the current subscription.

Just like the subscribe methods, upgrading also support dates as a third parameter if you plan to create a new subscription at the end of the current one.

Passing a fourth parameter is available, if your third parameter is false, and you should pass it if you'd like to mark the new subscription as recurring.

Extending current subscription

Upgrading uses the extension methods, so it uses the same arguments, but you do not pass as the first argument a Plan model:

Extending also works with dates:

Cancelling subscriptions

You can cancel subscriptions. If a subscription is not finished yet (it is not expired), it will be marked as pending cancellation. It will be fully cancelled when the expiration dates passes the current time and is still cancelled.

Consuming countable features

To consume the limit type feature, you have to call the consumeFeature() method within a subscription instance.

To retrieve a subscription instance, you can call activeSubscription() method within the user that implements the trait. As a pre-check, don't forget to call hasActiveSubscription() from the user instance to make sure it is subscribed to it.

The consumeFeature() method will return:

• false if the feature does not exist, the feature is not a limit or the amount is exceeding the current feature allowance
• true if the consumption was done successfully

If consumeFeature() meets an unlimited feature, it will consume it and it will also track usage just like a normal record in the database, but will never return false. The remaining will always be -1 for unlimited features.

The revering method for consumeFeature() method is unconsumeFeature(). This works just the same, but in the reverse:

Using the unconsumeFeature() method on unlimited features will also reduce usage, but it will never reach negative values.

Events

When using subscription plans, you want to listen for events to automatically run code that might do changes for your app.

Events are easy to use. If you are not familiar, you can check Laravel's Official Documentation on Events.

All you have to do is to implement the following Events in your EventServiceProvider.php file. Each event will have it's own members than can be accessed through the $event variable within the handle() method in your listener.

Testing

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

• Keoby
• Georgescu Alexandru Initial work
• Musa Kurt
• Dukens Thelemaque
• All Contributors

License

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