In Laravel, how do the Prunable and MassPrunable traits with php artisan model:prune remove old Eloquent records, and how do the two differ?

## The problem pruning solves A legal-case manager soft-deletes matters so they stay recoverable, and keeps audit and session-like records that lose value over time. Without cleanup these tables only grow. Eloquent's **pruning** feature lets each model declare which of its rows are obsolete, and one Artisan command removes them. ## Declaring what to prune ```php use Illuminate\Database\Eloquent\Builder; use Illuminate\Database\Eloquent\Prunable; use Illuminate\Database\Eloquent\SoftDeletes; class Matter extends Model { use Prunable, SoftDeletes; public function prunable(): Builder { return static::onlyTrashed() ->where('deleted_at', '<=', now()->subYears(7)) ->whereNull('legal_hold_at'); } protected function pruning(): void { Storage::deleteDirectory("matters/{$this->id}"); } } ``` A model with the trait but without `prunable()` throws a `LogicException` when pruned. ## Running it `php artisan model:prune` discovers models that use either trait under `app/Models` and prunes each. Its options, from the command's signature: - `--model=*` prunes only the given classes; `--except=*` skips some; - `--path=*` looks for models in other directories; - `--chunk=1000` sets how many records each chunk handles; - `--pretend` prints how many records would be pruned without deleting anything. Running it on a schedule is a scheduling concern; the command itself is a one-shot. ## Prunable versus MassPrunable | Aspect | `Prunable` | `MassPrunable` | |---|---|---| | How rows are removed | loads models with `chunkById()`, calls `prune()` on each | runs a limited delete query repeatedly | | `pruning()` hook | yes, before each delete | no | | Model events | yes (`deleting`, `deleted`, or force-delete events) | no | | Soft-deletable model | query gets `withTrashed()`; each model is `forceDelete()`d | builder `forceDelete()` | | Failure on one row | reported, the rest continue | the query fails as a whole | | Speed on millions of rows | slow: one delete per model | fast: one statement per chunk | ## Details that matter in production 1. **Soft-deleted models are force-deleted.** Pruning is permanent even for models that normally soft-delete; `Prunable::prune()` calls `forceDelete()` when the model uses `SoftDeletes`. 2. **Mass pruning skips global scopes.** The builder `forceDelete()` used for soft-deletable models runs without global scopes, so a tenant scope does not narrow it; the `prunable()` query must carry every condition it needs explicitly. 3. **Files and external state.** Only `Prunable` can clean up related files or remote records through `pruning()` or events. With `MassPrunable`, anything outside the table is orphaned. 4. **Events.** Each chunk dispatches a `ModelsPruned` event with the model class and running total, which the command uses for its output. 5. **Dry runs first.** `--pretend` is the safe first step whenever a `prunable()` query changes. ## A worked retention rule A firm's policy says archived matters are destroyed seven years after archiving, unless a legal hold is recorded. 1. `prunable()` returns `static::onlyTrashed()->where('deleted_at', '<=', now()->subYears(7))->whereNull('legal_hold_at')`, so live matters and held matters never match. 2. The model uses `Prunable`, because each matter has stored documents that `pruning()` must delete first. 3. Before the first real run, `php artisan model:prune --model="App\Models\Matter" --pretend` confirms the count looks right. 4. The command then runs on a schedule, and the `ModelsPruned` events give a per-run total for the audit log. If the documents lived in their own table with their own prunable rule, `MassPrunable` would be enough for the matters themselves. ## Choosing Use `Prunable` when deleting a row must also clean up something else, or observers must see the delete. Use `MassPrunable` for high-volume tables where each row is self-contained, such as logs or expired tokens.