README

A Laravel package that provides a comprehensive trash/soft-delete system with restore capabilities. When models are deleted, they are automatically moved to a trash bin where they can be viewed, restored, or permanently deleted.

Features

🗑️ Automatic Trash Management: Automatically saves deleted models to a trash table
🔄 Easy Restore: Restore deleted items with a single click
👁️ View Trash Items: Browse all trashed items through a web interface
🗂️ Model Agnostic: Works with any Eloquent model
🎨 Beautiful UI: Modern, responsive interface built with Tailwind CSS
🔒 Safe Deletion: Permanent deletion requires explicit action

Installation

Step 1: Install via Composer

composer require yeaminraat/laravel-trash

Step 2: Publish Migrations

php artisan vendor:publish --tag=laravel-trash-migrations

Step 3: Run Migrations

php artisan migrate

Step 4: (Optional) Publish Views

If you want to customize the trash views:

php artisan vendor:publish --tag=laravel-trash-views

Usage

Making Models Trashable

Add the Trashable trait to any Eloquent model you want to track:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use YeaminRaat\LaravelTrash\Traits\Trashable;

class Post extends Model
{
    use Trashable;

    protected $fillable = [
        'title',
        'content',
        'author_id',
    ];
}

Deleting Models

When you delete a model that uses the Trashable trait, it will automatically be saved to the trash table:

$post = Post::find(1);
$post->delete(); // Automatically saved to trash

Restoring Models

You can restore a model from trash using the restoreFromTrash() method:

$post = Post::find(1);
$result = $post->restoreFromTrash();

if ($result['status'] === 'success') {
    echo $result['message']; // "Restored successfully"
} else {
    echo $result['message']; // Error message
}

Accessing the Trash Interface

The package provides a web interface to manage trash items. Access it at:

http://your-app.test/trash

Available Routes:

GET /trash - View all trash items
GET /trash/{id} - View details of a specific trash item
POST /trash/restore/{id} - Restore a trash item
DELETE /trash/delete/{id} - Permanently delete a trash item

Programmatic Trash Management

You can also manage trash programmatically:

use YeaminRaat\LaravelTrash\Models\Trash;

// Get all trash items
$trashItems = Trash::latest()->get();

// Get trash for a specific model
$postTrash = Trash::where('model_type', Post::class)->get();

// Restore via controller logic
$trashItem = Trash::find(1);
$model = new $trashItem->model_type();
$record = $model->find($trashItem->model_id);

if ($record) {
    $record->update($trashItem->data);
} else {
    $model->create($trashItem->data);
}
$trashItem->delete();

How It Works

Deletion: When a model using the Trashable trait is deleted, the bootTrashable() method intercepts the deletion event and saves the model's data to the trash table.
Storage: The trash table stores:
- model_type: The fully qualified class name of the deleted model
- model_id: The ID of the deleted model
- data: JSON representation of the model's attributes
- created_at: When the item was trashed
Restoration: When restoring, the package:
- Retrieves the trashed data
- Either updates the existing model (if it still exists) or creates a new one
- Removes the item from the trash table

Database Schema

The package creates a trash table with the following structure:

Schema::create('trash', function (Blueprint $table) {
    $table->id();
    $table->string('model_type');
    $table->unsignedBigInteger('model_id');
    $table->json('data');
    $table->timestamps();
});

Error Handling

The package handles common errors during restoration:

Unique Constraint Violations: If restoring would violate unique constraints, an error message is returned
General Exceptions: Any unexpected errors are caught and reported

Requirements

PHP >= 8.0
Laravel >= 8.0

Author

Md Eamin Hossain

Email: yeaminhossain2@gmail.com

License

This package is open-sourced software. Please check the license file for more details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

If you encounter any issues or have questions, please open an issue on the GitHub repository.

yeaminraat / laravel-trash

Maintainers

Details