mvdnbrk / laravel-model-expires

A package to assign expiration dates to Eloquent models.

---

Assign expiration dates to Eloquent models

Installation

You can install the package via composer:

composer require mvdnbrk/laravel-model-expires

Usage

To use an expiration date on a model, use the Expirable trait:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Mvdnbrk\EloquentExpirable\Expirable;

class Subscription extends Model
{
    use Expirable;
}

You should add an expires_at column to your database table.
This packages contains a helper method to create this column:

class CreateSubscriptionsTable extends Migration
{
    public function up(): void
    {
        Schema::create('subscriptions', function (Blueprint $table) {
            $table->expires();
        });
    }

    public function down(): void
    {
        Schema::dropExpires();
    }
}

The Expirable trait will automatically cast the expires_at attribute to a DateTime / Carbon instance for you.

Customizing the column name

You may customize the column name by setting the EXIRES_AT constant or by overriding the getExpiresAtColumn method on your model.

class Subscription extends Model
{
    use Expirable;

    const EXPIRES_AT = 'ends_at';
}

$table->expires('ends_at');
$table->dropExpires('ends_at');

Setting expiration

You may set the expiration of a model by setting the expires_at attribute with a TTL in seconds:

$subscription->expires_at = 600;

Instead of passing the number of seconds as an integer, you may also pass a DateTime instance representing the expiration date:

$subscription->expires_at = now()->addMinutes(10);

Discarding expiration

You may discard the expiration of a model by setting a negative or zero TTL or use the discardExpiration method:

$subscription->expires_at = 0;
$subscription->expires_at = -5;

$subscription->discardExpiration()->save();

Determining expiration

To determine if a given model instance has expired, use the expired method:

if ($subscription->expired()) {
    //
}

To determine if a given model will expire in the future use the willExpire method:

if ($subscription->willExpire()) {
    //
}

Querying models

The withoutExpired method will retrieve models that are not expired:

$subscriptions = App\Models\Subscription::withoutExpired()->get();

The onlyExpired method will retrieve only the expired models:

$subscriptions = App\Models\Subscription::onlyExpired()->get();

The expiring method will retrieve only models that will expire in the future:

$subscriptions = App\Models\Subscription::expiring()->get();

The notExpiring method will retrieve only models that will not expire:

$subscriptions = App\Models\Subscription::notExpiring()->get();

Todo

• Add a expired:prune console command to delete expired models, or perform custom implementation.
• Add a query scope that will query models that will expire in ...

Testing

composer test

Changelog

Please see CHANGELOG for more information what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Mark van den Broek
• All Contributors

License

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

laravel-model-expires's Issues

Suggest : expiringIn method

Hello;

Thanks for this nice package.
You may add expiringIn method which is helpful for notifications before expired date.
example:
$subscriptions = App\Models\Subscription::expiringIn('x months/days/hours')->get(); // Get subscriptions will expire in x months/days/hours from now.

Thanks.

Some criticism of this package

First of all, apologies to disregard the template. I'd like to get straight to the point on a few issues.

1. Expired records are not excluded by default, which isn't expected behaviour and causes end users to hack up their own way (this should be done in the apply method of the scope class).
2. Regarding setExpiresAtAttribute:
   1. Setting the value of expires_at is very weird - there's a lot of funny parsing going on when instead it should have been a simple is_int($x) ? Carbon::now()->addSeconds($x) : $x - the current code somehow doesn't work for me in a simple test with timestamps and Carbon::setTestNow()
   2. If the dev named the column something else the setExpiresAtAttribute code will not be triggered for the other column name - this could be confusing/misleading
3. Regarding the Expirable trait:
   1. It is missing method PHPDoc (it should document the macros from ExpiringScope).
   2. Instead of redeclaring @property $attributes and @property $dates in that trait, maybe use @mixin HasAttributes instead.
   3. Careful that even if getSeconds trait method is protected, it could come down to some nasty incompatibility with other traits or implementing class. Same situation with importing all the methods from InteractsWithTime trait.
4. I'd consider better names for the macros, for example Subscription::withoutExpiration is more idiomatic than notExpiring.

---

On a different perspective, there's a competing package that solves some issues above but has its own problems.
Maybe consider partnering up to bring the best of both?