Home

Awesome

Laravel Usage Limiter

Tests

Introduction

A Laravel package to track, limit, & restrict usages of users, accounts, or any other model.

Features

Use cases

Basically with this package you can track your users' or any other models' usages and restrict them when they hit their maximum limits.

Example use-cases:

Versions

Compatible for Laravel versions >= 8.0.

Quick Tutorial

This README documentation serves more as a reference. For a step-by-step getting started tutorial check https://nabilhassen.com/laravel-usage-limiter-manage-rate-and-usage-limits and you can always refer to this README documentation for details and advanced stuff.

Installation

Install Laravel Usage Limiter using the Composer package manager:

composer require nabilhassen/laravel-usage-limiter

Next, you should publish the Laravel Usage Limiter configuration and migration files using the vendor:publish Artisan command:

php artisan vendor:publish --provider="NabilHassen\LaravelUsageLimiter\ServiceProvider"

Finally, you should run the migrate command in order to create the tables needed to store Laravel Usage Limiter's data:

php artisan migrate

Basic Usage

First, you need to use the HasLimits trait on your model.

use NabilHassen\LaravelUsageLimiter\Traits\HasLimits;

class User extends Authenticatable
{
    use HasLimits;
}

Create your Limits

# On standard plan 5 projects are allowed per month
$projectsStandardLimit = Limit::create([
    'name' => 'projects',
    'allowed_amount' => 5,
    'plan' => 'standard', // optional
    'reset_frequency' => 'every month' // optional
]);

# On pro plan 10 projects are allowed per month
$projectsProLimit = Limit::create([
    'name' => 'projects',
    'allowed_amount' => 10,
    'plan' => 'pro', // optional
    'reset_frequency' => 'every month' // optional
]);

# Increment projects limit on standard plan from 5 to 15 per month
$projectsStandardLimit->incrementBy(10);

# Decrement projects limit on pro plan from 10 to 7 per month
$projectsProLimit->decrementBy(3);
Possible values for "reset_frequency" column

Set Limits on models

$user->setLimit('projects', 'standard'); OR
$user->setLimit($projectsStandardLimit);

Set Limits on models with beginning used amounts

If a user has already consumed limits then:

$user->setLimit('projects', 'standard', 2); OR
$user->setLimit($projectsStandardLimit, usedAmount: 2);

Unset Limits from models

$user->unsetLimit('projects', 'standard'); OR
$user->unsetLimit($projectsStandardLimit);

Consume/Unconsume Limits

# When a user creates a project
$user->useLimit('projects', 'standard'); OR
$user->useLimit($projectsStandardLimit);

# When a user creates multiple projects
$user->useLimit('projects', 'standard', 3); OR
$user->useLimit($projectsStandardLimit, amount: 3);

# When a user deletes a project
$user->unuseLimit('projects', 'standard'); OR
$user->unuseLimit($projectsStandardLimit);

# When a user deletes multiple projects
$user->unuseLimit('projects', 'standard', 3); OR
$user->unuseLimit($projectsStandardLimit, amount: 3);
Both useLimit and unuseLimit methods throws an exception if a user exceeded limits or tried to unuse limits below 0.

Reset Limits for models

$user->resetLimit('projects', 'standard'); OR
$user->resetLimit($projectsStandardLimit);

All available methods

MethodReturn TypeParameters
setLimittrue|throwstring|Limit $limit, <br> ?string $plan = null, <br> float|int $usedAmount = 0.0
unsetLimitboolstring|Limit $limit, <br> ?string $plan = null
isLimitSetboolstring|Limit $limit, <br> ?string $plan = null
useLimittrue|throwstring|Limit $limit, <br> ?string $plan = null, <br> float|int $amount = 1.0
unuseLimittrue|throwstring|Limit $limit, <br> ?string $plan = null, <br> float|int $amount = 1.0
resetLimitboolstring|Limit $limit, <br> ?string $plan = null
hasEnoughLimitboolstring|Limit $limit, <br> ?string $plan = null
usedLimitfloatstring|Limit $limit, <br> ?string $plan = null
remainingLimitfloatstring|Limit $limit, <br> ?string $plan = null
limitUsageReportarraystring|Limit|null $limit = null, <br> ?string $plan = null

All available commands

CommandArgumentsExample
limit:createname: required <br> allowed_amount: required <br> plan: optionalphp artisan limit:create --name products --allowed_amount 20 --plan premium
limit:deletename: required <br> plan: optionalphp artisan limit:delete --name products --plan premium
limit:listNonephp artisan limit:list
limit:resetNonephp artisan limit:reset # reset limit usages to 0
limit:cache-resetNonephp artisan limit:cache-reset # flushes limits cache

Blade

# Using limit instance
@limit($user, $projectsStandardLimit)
    // user has enough limits left
@else
    // user has NO enough limits left
@endlimit

# Using limit name and plan
@limit($user, 'projects', 'standard')
    // user has enough limits left
@else
    // user has NO enough limits left
@endlimit

Schedule Limit Usage Resetting

The limit:reset command will reset your model's (e.g. user) limit usages based on the Limit's reset_frequency.

Add limit:reset command to the console kernel.

// app/Console/Kernel.php
protected function schedule(Schedule $schedule)
{
    ...
    // Laravel < 10
    $schedule->command('limit:reset')->everyMinute();

    // Laravel >= 10
    $schedule->command('limit:reset')->everySecond();
    ...
}

Advanced Usage

Extending

Clear your config cache if you have made any changes in the limit.php config file.

Caching

By default, Laravel Usage Limiter uses the default cache you chose for your app. If you would like to use any other cache store you will need to change the store key in the limit.php config file to your preferred cache store.

Manual Cache Reset

In your code

app()->make(\NabilHassen\LaravelUsageLimiter\LimitManager::class)->flushCache();

Via command line

php artisan limit:cache-reset

Testing

composer test

Security

If you have found any security issues, please send an email to the author at hello@nabilhassen.com.

Contributing

You are welcome to contribute to the package and you will be credited. Just make sure your PR does one thing and add tests.

License

The Laravel Usage Limiter is open-sourced software licensed under the MIT license MIT license.