From 0fa114f916d3dda23371c4b8be6473ba7250a407 Mon Sep 17 00:00:00 2001 From: Nuno Maduro Date: Wed, 7 Jul 2021 15:58:46 +0100 Subject: [PATCH 1/3] Update eloquent.md --- eloquent.md | 63 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) diff --git a/eloquent.md b/eloquent.md index 82321871043..ebf2390c7c8 100644 --- a/eloquent.md +++ b/eloquent.md @@ -25,6 +25,7 @@ - [Deleting Models](#deleting-models) - [Soft Deleting](#soft-deleting) - [Querying Soft Deleted Models](#querying-soft-deleted-models) +- [Prune Models](#prune-models) - [Replicating Models](#replicating-models) - [Query Scopes](#query-scopes) - [Global Scopes](#global-scopes) @@ -880,6 +881,68 @@ The `onlyTrashed` method will retrieve **only** soft deleted models: ->where('airline_id', 1) ->get(); + +## Prune Models + +Sometimes you may want to periodically delete models that are no longer needed. So, in those cases, add the `Illuminate\Database\Eloquent\Prunable` or `Illuminate\Database\Eloquent\MassPrunable` trait to the models you would like to periodically prune, and implement a `prunable` method that determines the models that are no longer needed: + + where('created_at', '<=', now()->subMonth()); + } + } + +When making models `Prunable`, you may also specify a `pruning` method that is called before the model gets deleted. This method can be useful for deleting any custom resources associated with the model, before the model gets permanently removed. + + /** + * Prepare the model for pruning. + * + * @return void + */ + protected function pruning() + { + // + } + +On the other hand, when making models `MassPrunable`, the method `pruning` method won't be called, and the `delete`, and `deleting` model events will not be fired for the deleted models. This is because the models are never actually retrieved. Making the entire pruning process much faster. + +Finally, you should schedule the `model:prune` Artisan command in your `App\Console\Kernel` class to run daily: + + /** + * Define the application's command schedule. + * + * @param \Illuminate\Console\Scheduling\Schedule $schedule + * @return void + */ + protected function schedule(Schedule $schedule) + { + $schedule->command('model:prune')->daily(); + } + +Behind the scenes, the `model:prune` artisan command will automatically detect "Prunable" models in the `app/Models` folder. Yet, if your models are in a different location, you may use the `--model` artisan option to specify the model class names: + + $schedule->command('model:prune', [ + '--model' => Flight::class, // or [Flight::class, Address::class] + ])->daily(); + +> {note} When using the "SoftDeletes" trait, soft deleted models will be permanently removed if they match the prunable query. + ## Replicating Models From 9e885d5ef373f5c90df3c03cf4f1c87463fdc4c1 Mon Sep 17 00:00:00 2001 From: Nuno Maduro Date: Wed, 7 Jul 2021 16:01:56 +0100 Subject: [PATCH 2/3] Updates title --- eloquent.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/eloquent.md b/eloquent.md index ebf2390c7c8..323a37e83f4 100644 --- a/eloquent.md +++ b/eloquent.md @@ -25,7 +25,7 @@ - [Deleting Models](#deleting-models) - [Soft Deleting](#soft-deleting) - [Querying Soft Deleted Models](#querying-soft-deleted-models) -- [Prune Models](#prune-models) +- [Pruning Models](#pruning-models) - [Replicating Models](#replicating-models) - [Query Scopes](#query-scopes) - [Global Scopes](#global-scopes) @@ -881,8 +881,8 @@ The `onlyTrashed` method will retrieve **only** soft deleted models: ->where('airline_id', 1) ->get(); - -## Prune Models + +## Pruning Models Sometimes you may want to periodically delete models that are no longer needed. So, in those cases, add the `Illuminate\Database\Eloquent\Prunable` or `Illuminate\Database\Eloquent\MassPrunable` trait to the models you would like to periodically prune, and implement a `prunable` method that determines the models that are no longer needed: From 8e9e47701a9e19424ca6c1ae4c4f1028b8c58437 Mon Sep 17 00:00:00 2001 From: Taylor Otwell Date: Wed, 7 Jul 2021 12:18:25 -0500 Subject: [PATCH 3/3] formatting --- eloquent.md | 53 +++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 39 insertions(+), 14 deletions(-) diff --git a/eloquent.md b/eloquent.md index 323a37e83f4..9b16cf83ee2 100644 --- a/eloquent.md +++ b/eloquent.md @@ -884,31 +884,31 @@ The `onlyTrashed` method will retrieve **only** soft deleted models: ## Pruning Models -Sometimes you may want to periodically delete models that are no longer needed. So, in those cases, add the `Illuminate\Database\Eloquent\Prunable` or `Illuminate\Database\Eloquent\MassPrunable` trait to the models you would like to periodically prune, and implement a `prunable` method that determines the models that are no longer needed: +Sometimes you may want to periodically delete models that are no longer needed. In those cases, you may add the `Illuminate\Database\Eloquent\Prunable` or `Illuminate\Database\Eloquent\MassPrunable` trait to the models you would like to periodically prune. After adding one of the traits to the model, implement a `prunable` method which returns an Eloquent query builder that resolves the models that are no longer needed: where('created_at', '<=', now()->subMonth()); + return static::where('created_at', '<=', now()->subMonth()); } } -When making models `Prunable`, you may also specify a `pruning` method that is called before the model gets deleted. This method can be useful for deleting any custom resources associated with the model, before the model gets permanently removed. +When marking models as `Prunable`, you may also define a `pruning` method on the model. This method will be called called before the model is deleted. This method can be useful for deleting any additional resources associated with the model, such as stored files, before the model is permanently removed from the database: /** * Prepare the model for pruning. @@ -919,10 +919,8 @@ When making models `Prunable`, you may also specify a `pruning` method that is c { // } - -On the other hand, when making models `MassPrunable`, the method `pruning` method won't be called, and the `delete`, and `deleting` model events will not be fired for the deleted models. This is because the models are never actually retrieved. Making the entire pruning process much faster. -Finally, you should schedule the `model:prune` Artisan command in your `App\Console\Kernel` class to run daily: +After configuring your prunable model, you should schedule the `model:prune` Artisan command in your application's `App\Console\Kernel` class. You are free to choose the appropriate interval at which this command should be run: /** * Define the application's command schedule. @@ -935,13 +933,40 @@ Finally, you should schedule the `model:prune` Artisan command in your `App\Cons $schedule->command('model:prune')->daily(); } -Behind the scenes, the `model:prune` artisan command will automatically detect "Prunable" models in the `app/Models` folder. Yet, if your models are in a different location, you may use the `--model` artisan option to specify the model class names: +Behind the scenes, the `model:prune` command will automatically detect "Prunable" models within your application's `app/Models` directory. If your models are in a different location, you may use the `--model` option to specify the model class names: - $schedule->command('model:prune', [ - '--model' => Flight::class, // or [Flight::class, Address::class] - ])->daily(); + $schedule->command('model:prune', [ + '--model' => [Address::class, Flight::class], + ])->daily(); -> {note} When using the "SoftDeletes" trait, soft deleted models will be permanently removed if they match the prunable query. +> {note} Soft deleting models will be permanently deleted (`forceDelete`) if they match the prunable query. + + +#### Mass Pruning + +When models are marked with the `Illuminate\Database\Eloquent\MassPrunable` trait, models are deleted from the database using mass-deletion queries. Therefore, the `pruning` method will not be invoked, nor will the `deleting` and `deleted` model events be dispatched. This is because the models are never actually retrieved before deletion, thus making the pruning process much more efficient: + + subMonth()); + } + } ## Replicating Models