Download the PHP package alajusticia/laravel-expirable without Composer

Laravel Expirable 📅

Inspired by the SoftDeletes trait, this package provides a trait to make Eloquent models expirable.

It relies on an additional attribute (named expires_at by default) that contains the date of expiration (or null to make the model eternal).

When the expiration date is reached, the model will automatically disappear from all the Eloquent query results (but still remain in the database).

• Compatibility
• Installation
  • Prepare your model
  • Change the default name of the expiration attribute
  • Set a default period of validity
  • Prepare your migration
• Usage
  • Retrieving models
  • Retrieving valid models
  • Retrieving all models
  • Retrieving only expired models
  • Retrieving only eternal models
  • Retrieving expired models since
  • Get the expiration date
  • Set the expiration date manually
  • The basic way
  • Using expiresAt()
  • Using lifetime()
  • Make existing models expire
  • Expire models by key
  • Expire models by query
  • Revive expired models
  • Make existing models eternal
  • Extend model lifetime
  • Shorten model lifetime
  • Reset the expiration date to default
  • Get the status of a model
  • Purge expired records
• License

Compatibility

You're reading the documentation for the latest version (v2) of this package.

Installation

Install the package via composer using this command:

You can publish the configuration file with:

Prepare your model

To make a model expirable, add the Expirable trait provided by this package:

This trait will automatically add the expiration attribute in the list of attributes that should be mutated to dates.

Default name of the expiration attribute

By default the package adds an attribute named expires_at on your model. You can change this name by setting the EXPIRES_AT constant (don't forget to set the same name for the column in the migration, see below).

For example, let's say that we have a Subscription model and we want the attribute to be ends_at:

You can also change the attribute name globally for all your expirable models by using the attribute_name option in the expirable.php configuration file (the constant prevails). If you do change the name globally in the configuration file, you don't have to set the name in the migration as it will be populated automatically.

Set a default period of validity

You can set a default period of validity with the defaultExpiresAt public static function.

This method must return a date object or null. This way, on saving the model the date of expiration will be automatically added unless you explicitly provide a date.

An example to set a default period of validity of six months:

Prepare your migration

The package requires that you add the expirable column in your migration. For convenience, the package provides the expirable() and dropExpirable() blueprint macros ready to use in your migration files:

By default the name of the database column, like the model attribute, will be expires_at or the one in the configuration file. If you modified the default name of the attribute on your model with the EXPIRES_AT constant, you need to set the same custom name for the column in your migration, by giving the macro a parameter with the name.

To continue with our subscription example:

Usage

Retrieving models

Retrieving valid models

Do your stuff as usual. By default, when the date of expiration is reached, the model will automatically be excluded of the results.

For example:

This, and all the next examples, work as well with relationships:

Retrieving all models

To disable the default filtering and retrieve all the models, ignoring their expiration date:

Retrieving only expired models

Use the onlyExpired scope:

Retrieving only eternal models

To get only the models which do not expire (with expiration date attribute to null), use the onlyEternal scope:

Retrieving expired models since

This package provides a query scope to retrieve only models that have expired for at least a given period of time. Use the expiredSince scope and give it a parameter representing the desired period of time.

The parameter must be a string and the syntax is the same as the syntax accepted by the Carbon sub method (see documentation here: https://carbon.nesbot.com/docs/#api-addsub).

For example, let's say that you want to definitively delete from the database the models expired since at least one year, the query will be:

Get the expiration date

To get the expiration date without having to know the name of its attribute, use the getExpirationDate method:

Set the expiration date manually

The basic way

If you know the name of the expiration date attribute, you can simply populate this attribute with a date object (or null for eternal):

Of course it also works with mass assignment, but don't forget to add the attribute you intend to mass assign (here ends_at) in the $fillable property of your model:

Using expiresAt()

Use the expiresAt method with a date object in parameter (or null for eternal) to set an expiration date manually. On an Eloquent query the changes will be directly saved in the database. On a single model you still need to use the save method:

Using lifetime()

The lifetime method provides you a more human readable way to set the period of validity with a string. The parameter must be a string and the syntax is the same as the syntax accepted by the Carbon add method (see documentation here: https://carbon.nesbot.com/docs/#api-addsub).

Make existing models expire

If you want a model to expire, use the expire method on a model instance. This will set the expiration date at the current timestamp.

Expire models by key

If you know the primary key of the model, you may make it expire without retrieving it by calling the expireByKey method. In addition to a single primary key as its argument, the expireByKey method will accept multiple primary keys, an array of primary keys, or a collection of primary keys:

Expire models by query

You can also run an expire statement on a set of models:

Revive expired models

After a model has expired, you can make it valid again using revive() method. It accepts an optional parameter which can be a date object or null for the new period of validity. Without parameter it resets to the default expiration date or set the expiration attribute to null if no default expiration date is set (making the model eternal).

Sure, it also works with queries:

Make existing models eternal

If you want a model never to expire, you just have to set the expiration attribute to null. You can do that manually or for existing models you can use the provided shortcut method makeEternal():

Extend model lifetime

With the extendLifetimeBy, you can extend the model lifetime by a human readable period (using the same syntax as the lifetime method):

In the same way, you have the ability to shorten the model lifetime with the shortenLifetimeBy method:

Shorten model lifetime

Reset the expiration date to default

You can reset the expiration date to its default value (null or the date returned by the defaultExpiresAt static function):

Get the status of a model

You can call the isExpired() and isEternal() methods on an expirable model instance. For example:

Purge expired records

This package comes with a command to delete expired records from the database:

You have two ways to indicate which models should be purged:

• add their class to the purge array of the configuration file:

• pass one or several classes in argument of the purge command:

Models passed as arguments take precedence (the purge array in the configuration file will be ignored).

You can also specify a period of time to delete models expired since that given period, using the since option (the value of this option is passed to the expiredSince query scope):

By default, this command will use force deletion to purge the models. If needed, you can specify the mode option with the value soft to perform a soft delete:

:warning: Be aware that if you try to purge models depending on tables with foreign key constraints using the default hard mode, you will have to specify the desired action for the "on delete" property of the constraint (for example using the onDelete('cascade'), cascadeOnDelete() or nullOnDelete() modifiers on the foreign key in your migrations: https://laravel.com/docs/10.x/migrations#foreign-key-constraints) or purge the child models first (ordering the command arguments or the array in the config file to start with the children) to avoid SQL errors.

License

Open source, licensed under the MIT license.