{"id":32610536,"url":"https://github.com/maize-tech/laravel-model-expires","last_synced_at":"2025-10-30T13:50:19.547Z","repository":{"id":206399521,"uuid":"716558115","full_name":"maize-tech/laravel-model-expires","owner":"maize-tech","description":"Add expiration date to any model and exclude expired models from queries.","archived":false,"fork":false,"pushed_at":"2025-07-28T17:38:55.000Z","size":120,"stargazers_count":22,"open_issues_count":1,"forks_count":2,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-07-28T19:30:06.005Z","etag":null,"topics":["eloquent","exclude","expiration","laravel"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/maize-tech.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-11-09T11:44:23.000Z","updated_at":"2025-07-28T17:38:53.000Z","dependencies_parsed_at":null,"dependency_job_id":"b2c4bdc9-ce3a-4460-b17b-43235f1c2b0a","html_url":"https://github.com/maize-tech/laravel-model-expires","commit_stats":null,"previous_names":["maize-tech/laravel-model-expires"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/maize-tech/laravel-model-expires","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maize-tech%2Flaravel-model-expires","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maize-tech%2Flaravel-model-expires/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maize-tech%2Flaravel-model-expires/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maize-tech%2Flaravel-model-expires/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/maize-tech","download_url":"https://codeload.github.com/maize-tech/laravel-model-expires/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maize-tech%2Flaravel-model-expires/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":281818074,"owners_count":26566858,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-30T02:00:06.501Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["eloquent","exclude","expiration","laravel"],"created_at":"2025-10-30T13:50:17.351Z","updated_at":"2025-10-30T13:50:19.540Z","avatar_url":"https://github.com/maize-tech.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n\u003cpicture\u003e\n  \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"/art/socialcard-dark.png\"\u003e\n  \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"/art/socialcard-light.png\"\u003e\n  \u003cimg src=\"/art/socialcard-light.png\" alt=\"Social Card of Laravel Model Expires\"\u003e\n\u003c/picture\u003e\n\u003c/p\u003e\n\n# Laravel Model Expires\n\n[![Latest Version on Packagist](https://img.shields.io/packagist/v/maize-tech/laravel-model-expires.svg?style=flat-square)](https://packagist.org/packages/maize-tech/laravel-model-expires)\n[![GitHub Tests Action Status](https://img.shields.io/github/actions/workflow/status/maize-tech/laravel-model-expires/run-tests.yml?branch=main\u0026label=tests\u0026style=flat-square)](https://github.com/maize-tech/laravel-model-expires/actions?query=workflow%3Arun-tests+branch%3Amain)\n[![GitHub Code Style Action Status](https://img.shields.io/github/actions/workflow/status/maize-tech/laravel-model-expires/fix-php-code-style-issues.yml?branch=main\u0026label=code%20style\u0026style=flat-square)](https://github.com/maize-tech/laravel-model-expires/actions?query=workflow%3A\"Fix+PHP+code+style+issues\"+branch%3Amain)\n[![Total Downloads](https://img.shields.io/packagist/dt/maize-tech/laravel-model-expires.svg?style=flat-square)](https://packagist.org/packages/maize-tech/laravel-model-expires)\n\nWith this package you can add expiration date to any model and exclude expired models from queries.\nWhen needed, you could send a notification for expiring models.\nYou can also set a deletion date for every model and automatically clean them up with a command.\n\n## Installation\n\nYou can install the package via composer:\n\n```bash\ncomposer require maize-tech/laravel-model-expires\n```\n\nYou can publish the config and migration files and run the migrations with:\n\n```bash\nphp artisan model-expires:install\n```\n\nThis is the contents of the published config file:\n\n```php\nreturn [\n\n    /*\n    |--------------------------------------------------------------------------\n    | Expiration model\n    |--------------------------------------------------------------------------\n    |\n    | Here you may specify the fully qualified class name of the expiration model.\n    |\n    */\n\n    'expiration_model' =\u003e Maize\\ModelExpires\\Models\\Expiration::class,\n\n    'model' =\u003e [\n\n        /*\n        |--------------------------------------------------------------------------\n        | Expires after days\n        |--------------------------------------------------------------------------\n        |\n        | Here you may specify the default amount of days after which a model\n        | should expire.\n        | If null, all newly created models won't have a default expiration date.\n        |\n        */\n\n        'expires_after_days' =\u003e null,\n\n        /*\n        |--------------------------------------------------------------------------\n        | Deletes after days\n        |--------------------------------------------------------------------------\n        |\n        | Here you may specify the default amount of days after which a model\n        | should be deleted.\n        | If null, all newly created models won't have a default deletion date.\n        |\n        */\n\n        'deletes_after_days' =\u003e null,\n    ],\n\n    'expiring_notification' =\u003e [\n\n        /*\n        |--------------------------------------------------------------------------\n        | Enable expiring notification\n        |--------------------------------------------------------------------------\n        |\n        | Here you may specify whether you want to enable model expiring\n        | notifications or not.\n        |\n        */\n\n        'enabled' =\u003e true,\n\n        /*\n        |--------------------------------------------------------------------------\n        | Notification class\n        |--------------------------------------------------------------------------\n        |\n        | Here you may specify the fully qualified class name of the default notification.\n        | If null, no notifications will be sent.\n        |\n        */\n\n        'notification' =\u003e Maize\\ModelExpires\\Notifications\\ModelExpiringNotification::class,\n\n        /*\n        |--------------------------------------------------------------------------\n        | Notifiable emails\n        |--------------------------------------------------------------------------\n        |\n        | Here you may specify the default list of notifiable email addresses.\n        |\n        */\n\n        'notifiables' =\u003e [\n            //\n        ],\n    ],\n];\n```\n\n## Usage\n\n### Basic\n\nTo use the package, add the `Maize\\ModelExpires\\HasExpiration` trait to all models you want to have an expiration date:\n\n``` php\n\u003c?php\n\nnamespace App\\Models;\n\nuse Illuminate\\Database\\Eloquent\\Model;\nuse Maize\\ModelExpires\\HasExpiration;\n\nclass User extends Model\n{\n    use HasExpiration;\n}\n```\n\nThat's it! All you have to do from now on is calling the `setExpiresAt` method every time you want to set an expiration and/or deletion date:\n\n``` php\n$user = User::create([])-\u003esetExpiresAt(\n    expiresAt: now()-\u003eaddDays(5),\n    deletesAt: now()-\u003eaddDays(10),\n); // user will have both an expiration and deletion date\n\n$user = User::create([])-\u003esetExpiresAt(\n    expiresAt: now()-\u003eaddDays(5)\n); // user will have an expiration date but will not be deleted\n```\n\n### Checking expiration and deletion days left\n\nYou can also check whether a model is expired and calculate the amount of days before its expiration (or deletion):\n\n``` php\n$user = User::create([])-\u003esetExpiresAt(\n    expiresAt: now()-\u003eaddDays(5),\n    deletesAt: now()-\u003eaddDays(10),\n);\n\n$user-\u003eisExpired(); // returns false\n\n$user-\u003egetDaysLeftToExpiration(); // returns 5\n$user-\u003egetDaysLeftToDeletion(); // returns 10\n\n\n$user = User::create([])-\u003esetExpiresAt(\n    expiresAt: now()-\u003esubDay()\n);\n\n$user-\u003eisExpired(); // returns true\n\n$user-\u003egetDaysLeftToExpiration(); // returns 0, as the model is already expired\n$user-\u003egetDaysLeftToDeletion(); // returns null, as model does not have a deletion date\n```\n\n### Excluding expired models\n\nWhen you want to exclude expired models, all you have to do is use the `withoutExpired` scope method:\n\n``` php\n$user = User::create([]); // user does not have an expiration date\n$expiredUser = User::create([])-\u003esetExpiresAt(\n    expiresAt: now()-\u003esubDay(),\n); // user is already expired\n\nUser::withoutExpired()-\u003ecount(); // returns 1, which is the $user model\nUser::withoutExpired()-\u003eget(); // returns the $user model\n```\n\n\n### Retrieving only expired models\n\nWhen you want to retrieve expired models, all you have to do is use the `onlyExpired` scope method:\n\n``` php\n$user = User::create([]); // user does not have an expiration date\n$expiredUser = User::create([])-\u003esetExpiresAt(\n    expiresAt: now()-\u003esubDay(),\n); // user is already expired\n\nUser::onlyExpired()-\u003ecount() // returns 1, which is the $expiredUser model\nUser::onlyExpired()-\u003eget(); // returns the $expiredUser model\n```\n\n### Default expiration date\n\nIf you wish, you can define a default expiration date. This can be done in two ways.\n\nFirst, you can set a value for `expires_after_days` property under `config/model-expires.php` config file.\nWhen set, all models including the `Maize\\ModelExpires\\HasExpiration` trait will automatically have an expiration date upon its creation:\n\n``` php\nconfig()-\u003eset('model-expires.model.expires_after_days', 5);\n\n$user = User::create([]);\n$user-\u003egetDaysLeftToExpiration(); // returns 5\n```\n\nThe second way is overriding the `defaultExpiresAt` method within all models you want to have a default expiration date:\n\n``` php\n\u003c?php\n\nnamespace App\\Models;\n\nuse Illuminate\\Database\\Eloquent\\Model;\nuse Illuminate\\Support\\Carbon;\nuse Maize\\ModelExpires\\HasExpiration;\n\nclass User extends Model\n{\n    use HasExpiration;\n    \n    protected static function defaultExpiresAt(): ?Carbon\n    {\n        return now()-\u003eaddDays(10); // all user models will expire 10 days after being created\n    }\n}\n```\n\n``` php\n\u003c?php\n\nnamespace App\\Models;\n\nuse Illuminate\\Database\\Eloquent\\Model;\nuse Illuminate\\Support\\Carbon;\nuse Maize\\ModelExpires\\HasExpiration;\n\nclass Tenant extends Model\n{\n    use HasExpiration;\n    \n    protected static function defaultExpiresAt(): ?Carbon\n    {\n        return now()-\u003eaddMonth(); // all tenant models will expire 1 month after being created\n    }\n}\n```\n\n### Default deletion date\n\nIf you wish, you can define a default deletion date. This can be done in two ways.\n\nFirst, you can set a value for `deletes_after_days` property under `config/model-expires.php` config file.\nWhen set, all models including the `Maize\\ModelExpires\\HasExpiration` trait will automatically have a deletion date upon its creation:\n\n``` php\nconfig()-\u003eset('model-expires.model.deletes_after_days', 5);\n\n$user = User::create([]);\n$user-\u003egetDaysLeftToDeletion(); // returns 5\n```\n\nThe second way is overriding the `defaultDeletesAt` method within all models you want to have a default deletion date:\n\n``` php\n\u003c?php\n\nnamespace App\\Models;\n\nuse Illuminate\\Database\\Eloquent\\Model;\nuse Illuminate\\Support\\Carbon;\nuse Maize\\ModelExpires\\HasExpiration;\n\nclass User extends Model\n{\n    use HasExpiration;\n    \n    protected static function defaultDeletesAt(): ?Carbon\n    {\n        return now()-\u003eaddDays(10); // all user models will be deleted 10 days after being created\n    }\n}\n```\n\n``` php\n\u003c?php\n\nnamespace App\\Models;\n\nuse Illuminate\\Database\\Eloquent\\Model;\nuse Illuminate\\Support\\Carbon;\nuse Maize\\ModelExpires\\HasExpiration;\n\nclass Tenant extends Model\n{\n    use HasExpiration;\n    \n    protected static function defaultDeletesAt(): ?Carbon\n    {\n        return now()-\u003eaddMonth(); // all tenant models will be deleted 1 month after being created\n    }\n}\n```\n\n### Scheduling expiration check\n\nThe package comes with the `expires:check` command, which automatically fires a `ModelExpiring` event for all expiring models.\n\nTo do so, you should define how often you want to fire the event.\nAll you have to do is overriding the `fireExpiringEventBeforeDays` for all models using the `HasExpiration` trait:\n\n``` php\nuse Illuminate\\Database\\Eloquent\\Factories\\HasFactory;\n\nclass User extends Authenticatable\n{\n    use HasExpiration;\n\n    public static function fireExpiringEventBeforeDays(): array\n    {\n        return [5, 10]; // expiring events will be fired 5 and 10 days before each model's expiration\n    }\n}\n```\n\nBy default, the method returns an empty array, meaning models will never fire expiring events.\n\nOnce done, you can schedule the command on a daily basis using the `schedule` method of the console kernel (usually located under the `App\\Console` directory):\n\n``` php\nuse Maize\\ModelExpires\\Commands\\ModelExpiresDeleteCommand;\n\n$schedule-\u003ecommand(ModelExpiresCheckCommand::class)-\u003edaily();\n```\n\n### Scheduling models deletion\n\nThe package also comes with the `expires:delete` command, which automatically deletes all expired and deletable models.\nThis comes pretty useful when automatizing its execution using Laravel's scheduling.\nAll you have to do is add the following instruction to the `schedule` method of the console kernel (usually located under the `App\\Console` directory):\n\n``` php\nuse Maize\\ModelExpires\\Commands\\ModelExpiresDeleteCommand;\n\n$schedule-\u003ecommand(ModelExpiresDeleteCommand::class)-\u003edaily();\n```\n\n## Testing\n\n```bash\ncomposer test\n```\n\n## Changelog\n\nPlease see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.\n\n## Contributing\n\nPlease see [CONTRIBUTING](https://github.com/maize-tech/.github/blob/main/CONTRIBUTING.md) for details.\n\n## Security Vulnerabilities\n\nPlease review [our security policy](https://github.com/maize-tech/.github/security/policy) on how to report security vulnerabilities.\n\n## Credits\n\n- [Enrico De Lazzari](https://github.com/enricodelazzari)\n- [Riccardo Dalla Via](https://github.com/riccardodallavia)\n- [All Contributors](../../contributors)\n\n## License\n\nThe MIT License (MIT). Please see [License File](LICENSE.md) for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaize-tech%2Flaravel-model-expires","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaize-tech%2Flaravel-model-expires","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaize-tech%2Flaravel-model-expires/lists"}