A package to assign expiration dates to Eloquent models

Fund package maintenance!

v1.8.1 2020-11-11 21:13 UTC

This package is auto-updated.

Last update: 2021-04-15 10:56:54 UTC


Laravel Model Expires

PHP version Latest Version on Packagist Software License Tests Code style Total Downloads

Assign expiration dates to Eloquent models


You can install the package via composer:

composer require mvdnbrk/laravel-model-expires


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


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) {

    public function down(): void

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';

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;


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();


  • 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 ...


composer test


Please see CHANGELOG for more information what has changed recently.


Please see CONTRIBUTING for details.

Security Vulnerabilities

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



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