Laravel Model Iid Laravel Package

Getting Started

1. Upgrade to 0.1.2 — composer require <vendor>/<package>:^0.1.2. Soft deletes are an additive feature; nothing in the release note signals a breaking change from the 0.1.x line.
2. Check the schema. If the package owns its table, re-publish and diff the migration stub to confirm a nullable deleted_at column was added. If the table is yours, add $table->softDeletes() yourself — the trait will not create the column for you.
3. Enable the trait on the model(s) the package manages: use Illuminate\Database\Eloquent\SoftDeletes; inside the class body. If the package ships a base model, verify 0.1.2 already includes it rather than double-applying it.
4. Confirm the cast. On Laravel 10+ the trait handles deleted_at as a date automatically; older or heavily customised models may still need protected $dates = ['deleted_at'].
5. First use case: $record->delete() → the row stays in the table with a timestamp → Model::withTrashed()->find($id)->restore() brings it back.

Look first at the package's model/trait source and its migration stub, then the README section on deleting. Those two files tell you whether the package is managing the soft-delete lifecycle for you or just handing you the trait.

Implementation Patterns

• Default scoping does the filtering. All normal reads exclude trashed rows. Admin and history screens opt in explicitly with withTrashed() (show everything) or onlyTrashed() (recycle bin / restore UI).
• Route model binding respects global scopes, so trashed records 404. For restore endpoints, either bind with ->withTrashed() in the route definition or use Route::bind() with an explicit withTrashed() query.
• Restore flows need authorization and an audit trail. Pair restore() with a policy check, and hook the restored event (or an observer) to log who restored what and when.
• Relationships: a belongsTo pointing at a soft-deletable parent returns null when the parent is trashed. Decide per-relationship whether ->withTrashed() is appropriate — usually yes for historical records, no for live references.
• Soft delete does not cascade. Handle children in a deleting model event or a dedicated action/service class so the parent and children are always deleted together.
• Purge strategy: schedule Model::onlyTrashed()->where('deleted_at', '<', now()->subDays(30))->forceDelete() in a queued command, chunked with chunkById() on large tables.
• API serialisation: expose deleted_at in your resources, or add a trashed boolean accessor, so clients can distinguish live from deleted records without a second request.
• Testing: use assertSoftDeleted(), assertNotSoftDeleted(), and assertRestored() against the database rather than asserting on return values.

Gotchas and Tips

• Unique indexes will bite you. A soft-deleted row still occupies its unique email/username. Move to a partial/filtered index where supported, or a composite unique including deleted_at (MySQL needs care here because NULL doesn't collide the way you might expect).
• forceDelete() bypasses soft deletes entirely. Gate destructive endpoints separately from ordinary delete — they are not the same permission.
• Global scopes only apply to Eloquent. DB::table() queries and raw SQL will happily return trashed rows; don't mix them into the same reporting path.
• restore() on a non-trashed model is a silent no-op, not an exception. Call trashed() first if your endpoint needs to report failure.
• updateOrCreate can resurrect trashed rows if the lookup query is unscoped. Add withTrashed() deliberately or not at all.
• Queued jobs holding serialised models can fail to resolve on the worker once the record is trashed. Prefer passing IDs and re-querying with withTrashed() inside the job.
• Pre-1.0 caveat: at 0.1.2 the soft-delete surface is brand new. Pin the exact version, and re-read release notes on every bump — config flags and trait behaviour may shift before 1.0.
• Extension points: model events (deleting, deleted, restoring, restored, forceDeleted) and observers are the safest way to customise behaviour without forking the package.