README

^{plug-and-play global and model-specific cooldowns}

Laravel Cooldowns

This Laravel package makes it easier to implement cooldowns into your app.
Consider the following example:

// The user will be able to post again 5 minutes from now
$user->cooldown('create-post')->for('5 minutes');

Installation

You can install the package via composer:

composer require kurozora/laravel-cooldown

Usage

Global cooldowns

Global cooldowns aren't tied to any model and are the same throughout your entire app.
Use the cooldown helper to create one:

cooldown('registration')->for('1 hour');

Here's an example of how you could limit registration to once per hour:

if(cooldown('registration')->notPassed())
    return 'Registration is currently unavailable.';

// ... perform account registration ...

cooldown('registration')->for('1 hour');

Model-specific cooldowns

Of course, a more useful use-case would be to tie cooldowns to models. In order to make use of this, you'll need to add the trait to your model:

use Illuminate\Database\Eloquent\Model;
use Kurozora\Cooldown\HasCooldowns;

class User extends Model
{
    use HasCooldowns;
}

The API used to interact with model-specific cooldowns is the exact same as global cooldowns, however you use the cooldown method on the model itself:

if($user->cooldown('create-post')->notPassed())
    return 'You cannot create a post right now.';

// ... create the post ...

$user->cooldown('create-post')->for('5 minutes');

All cooldown methods

These methods are available for both global and model-specific cooldowns.

for() Cooldown for a timespan
Pass along a string with the desired timespan.

cooldown('create-post')->for('1 day 3 hours');

until() Cooldown for a given datetime
Pass along a Carbon object with the desired datetime.

$tomorrow = now()->addDay();

cooldown('create-post')->until($tomorrow);

reset() Reset the cooldown
The cooldown will be reset, and the action will be available immediately.

cooldown('create-post')->reset();

passed()
Checks whether the cooldown has passed. Returns true if the cooldown hasn't ever been initiated.

cooldown('create-post')->passed(); // true/false

notPassed()
Checks whether the cooldown is still active, and thus hasn't passed yet.

cooldown('create-post')->notPassed(); // true/false

expiresAt() Get the expiration date
Returns the datetime at which the cooldown will pass.

cooldown('create-post')->expiresAt(); // Illuminate\Support\Carbon object

get()
Returns the underlying Cooldown model.

cooldown('create-post')->get(); // Kurozora\Cooldown\Models\Cooldown object

Testing

composer test

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email kurozoraapp@gmail.com instead of using the issue tracker.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Musa 💻 📖

Kirito 🤔 🎨

This project follows the all-contributors specification. Contributions of any kind welcome!

License

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