Laravel Trash Laravel Package

Getting Started

• Install with composer require ajaycalicut17/laravel-trash and publish any package assets with php artisan vendor:publish --provider="Ajaycalicut17\LaravelTrash\LaravelTrashServiceProvider". Check the package README first for the exact service provider namespace and whether a config file or migration is shipped — v1.0.3 is still a 1.x release, so the public surface should match the README, but confirm before assuming.
• The core requirement for any trash-style package is that your Eloquent models already use Illuminate\Database\Eloquent\SoftDeletes. Add the package trait/interface to the models you want to manage through the trash UI or API, then run your migrations.
• Look first at the package's config/ and src/ directories after install. The config file (if present) is where route prefix, middleware, guard, and per-model registration typically live. If there is no config file, model registration is likely done via a trait or a static registry on the model itself.
• First use case: soft-delete a record through your app as normal ($post->delete()), then use the package to list trashed records and restore one ($post->restore() or the package's facade/endpoint, depending on how it exposes operations). Verify the restored record appears in your normal queries before wiring anything else.

v1.0.3 itself does not introduce new features: the changelog is a set of unspecified "Fix" commits plus CI workflow updates (PHPStan, PHP-CS-Fixer, PHPMD, test runner) and a Dependabot bump for peter-evans/create-pull-request. Treat it as a patch release and pin to ^1.0.3 if you were already on 1.0.x, but read the compare diff (v1.0.2...v1.0.3) because the "Fix" PRs have no descriptions and could touch runtime behavior.

Implementation Patterns

• Centralize trashed queries. Rather than sprinkling onlyTrashed()/withTrashed() through controllers, expose scoped methods or a repository per model. This keeps the trash UI, API, and scheduled cleanup reading from the same source of truth.
• Wrap restore/force-delete in authorization. The package can list and act on records across models; your Policy classes should still gate restore and forceDelete. Add explicit policy methods if you rely on the package's routes, since route-model binding on trashed records often needs withTrashed() binding to work at all.
• Use bulk operations deliberately. Restoring many records at once is convenient but should be chunked (->chunkById(500, ...)) when driven from the package's listing, and each restore should fire model events so your observers (audit logs, search indexing) stay consistent.
• Schedule pruning. Trash grows. Add a scheduled command or job that force-deletes records older than your retention window, and make the window configurable per model rather than hardcoding it. Run it in a queue if the volume is high.
• Audit and notify. Hook restoring, restored, forceDeleting, and forceDeleted events on your models to write audit entries. This is the easiest extension point and does not require touching the package internals.
• Integrate with your admin panel. If you use Filament, Nova, or a custom Blade admin, mount the package routes behind the same auth middleware as the rest of the panel. Don't expose the trash route publicly even if the package ships it enabled by default — check the route registration and gate it.
• Jobs and serialization. When a queued job holds a soft-deleted model and uses SerializesModels, the model is restored from the database on unserialize; confirm that trashed records resolve correctly and that a force-delete between dispatch and handle doesn't blow up the job. Prefer passing IDs and re-querying with withTrashed() explicitly.

Gotchas and Tips

• The deleted_at column is the contract. If a model's table lacks deleted_at or uses a custom column name, the package will silently skip it or throw confusing query errors. Audit which models you register.
• Unique constraints versus trashed rows. A soft-deleted row still occupies unique indexes. Restoring can fail if a new record took the same slug/email in the meantime. Decide on a policy (suffix trashed slugs, or catch the QueryException and surface a clear error) before users hit it in production.
• Route model binding. Trashed records won't resolve through implicit binding unless the route uses ->withTrashed(). If the package doesn't do this for you, you'll get 404s on restore endpoints and waste time debugging middleware.
• Config caching. If the package ships a config file, run php artisan config:clear after edits in local development; stale cached config is a common cause of "my model isn't showing in the trash" reports.
• Version pinning and the vague changelog. The 1.0.3 "Fix" commits are undocumented. If you're upgrading from 1.0.2, run your own restore/force-delete test suite against the new tag rather than trusting the patch-level bump. If something breaks, the compare diff on GitHub is the only reliable source.
• Debugging missing records. Start with Model::onlyTrashed()->whereKey($id)->exists() and Model::withTrashed()->find($id). If both work but the package list is empty, the problem is almost always model registration or the package's config/guard, not the data.
• Extension points. Favor model events and policies over forking. If you need custom behavior (e.g., cascade-restore relations), implement it in an observer or a restored listener so package upgrades stay painless.
• CI signals worth noting. The release adds PHPStan, PHP-CS-Fixer, and PHPMD workflows. That's a positive maintainability signal, but static-analysis-only changes won't catch runtime regressions in your app — your own feature tests around trash flows remain the real safety net.