PHPackages                             promethys/revive - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. promethys/revive

ActiveLibrary[Utility & Helpers](/categories/utility)

promethys/revive
================

A 'RecycleBin' page where users can restore or delete permanently soft-deleted models.

3.0.2(3mo ago)161.2k↓25%2MITPHPPHP ^8.2CI passing

Since Apr 5Pushed 3mo ago1 watchersCompare

[ Source](https://github.com/Promethys/revive)[ Packagist](https://packagist.org/packages/promethys/revive)[ Docs](https://github.com/Promethys/revive)[ GitHub Sponsors](https://github.com/Promethys)[ RSS](/packages/promethys-revive/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (17)Versions (20)Used By (0)

Filament RecycleBin for Laravel Models
======================================

[](#filament-recyclebin-for-laravel-models)

[![Latest Version on Packagist](https://camo.githubusercontent.com/4734ad4c60817784dd0e19a64ceac70ef8783ef52507f50232ebba13e399afb7/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f70726f6d65746879732f7265766976652e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/promethys/revive)[![GitHub Tests Action Status](https://camo.githubusercontent.com/8cf0d022539f85f117d289ee2e01c50e7395dcc904e7a939e401a1b52e00a769/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f70726f6d65746879732f7265766976652f72756e2d74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/promethys/revive/actions?query=workflow%3Arun-tests+branch%3Amain)[![Total Downloads](https://camo.githubusercontent.com/ac3fb4527e47d0bf73403410f660bbf055af51dfdbb60ea9fb7539043e31563c/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f70726f6d65746879732f7265766976652e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/promethys/revive)

If this plugin is useful to you, consider [giving it a ⭐ on GitHub](https://github.com/Promethys/revive).

**Revive** is a plugin for [FilamentPHP](https://filamentphp.com) that brings a central **Recycle Bin** to your application. It lets you restore or permanently delete soft-deleted Eloquent models in just a few clicks.

This plugin is especially useful for SaaS applications, admin dashboards, or any multi-user platform where recovering accidentally deleted data is important.

[![Preview Screenshot](https://raw.githubusercontent.com/Promethys/revive/refs/heads/main/resources/imgs/preview.png)](https://raw.githubusercontent.com/Promethys/revive/refs/heads/main/resources/imgs/preview.png)

---

Release Strategy
----------------

[](#release-strategy)

- **V1.x**: Legacy - Filament v3 (critical bug fixes only)
- **V2.x**: Maintenance mode - Filament v4
- **V3.x**: Active development - Filament v5

---

Features
--------

[](#features)

- View, restore, and permanently delete soft-deleted records from a dedicated Filament page
- Register multiple models as "Recyclable" with a simple trait
- Filter items by model type or search through deleted records
- Customize the plugin's appearance and behavior with ease
- State snapshots - stores model data at deletion time for reference
- Discover existing soft-deleted records with CLI command
- User and multi-tenancy support **(V2+)**

---

Installation
------------

[](#installation)

### Latest Version (V3 - Recommended - Filament v5)

[](#latest-version-v3---recommended---filament-v5)

Install the latest version for Filament v5:

```
composer require promethys/revive
php artisan revive:install
```

> **Requirements:** PHP 8.2+, Laravel 11+, Filament v5

### Version 2 (for Filament v4)

[](#version-2-for-filament-v4)

If you need to install V2 for Filament v4:

```
composer require promethys/revive:^2.0
php artisan revive:install
```

### Version 1 (for Filament v3)

[](#version-1-for-filament-v3)

If you need to install V1 for Filament v3:

```
composer require promethys/revive:^1.0
php artisan revive:install
```

### Manual Installation

[](#manual-installation)

If you prefer to manually publish and run the migrations:

```
php artisan vendor:publish --tag="revive-migrations"
php artisan migrate
```

### Upgrading from V2 to V3

[](#upgrading-from-v2-to-v3)

If you're currently using V2 and want to upgrade to V3 for Filament v5:

```
# 1. Ensure you have PHP 8.2+, Laravel 11/12, and Filament v5

# 2. Update your composer constraint
composer require promethys/revive:^3.0

# 3. Clear caches
php artisan config:clear
php artisan cache:clear
```

> **Note:** V3 has no database schema changes from V2. The upgrade primarily involves compatibility with Filament v5's API changes.

### Upgrading from V1 to V2

[](#upgrading-from-v1-to-v2)

If you're currently using V1 and want to upgrade to V2:

```
# 1. Update your composer constraint
composer require promethys/revive:^2.0

# 2. Publish and Run new migrations
php artisan vendor:publish --tag="revive-migrations"
php artisan migrate

# 3. Update your plugin configuration (see Configuration section below)
```

---

Configuration
-------------

[](#configuration)

Register the plugin in each panel where you want the recycle bin available:

```
use Promethys\Revive\RevivePlugin;

$panel->plugins([
    RevivePlugin::make()
]);
```

You can also customize the plugin using fluent configuration:

```
use Promethys\Revive\RevivePlugin;

$panel->plugins([
    RevivePlugin::make()
        ->authorize(auth()->user()->isAdmin()) // Accepts a boolean or Closure to control access
        ->navigationGroup('Settings') // Group the page under a custom sidebar section
        ->navigationIcon('heroicon-o-archive-box-arrow-down')
        ->activeNavigationIcon('heroicon-o-archive-box-arrow-down')
        ->navigationSort(1)
        ->navigationLabel('Custom Label')
        ->title('Custom Title')
        ->slug('custom-slug')
]);
```

### User and Multi-Tenancy Configuration

[](#user-and-multi-tenancy-configuration)

Revive provides powerful scoping features that allow users to see only their own deleted items or items within their tenant/organization:

```
use Promethys\Revive\RevivePlugin;

// Basic user-scoped recycle bin (users only see their own deleted items)
$panel->plugins([
    RevivePlugin::make()
        ->enableUserScoping() // Default: true
        ->enableTenantScoping(false)
]);

// Multi-tenant recycle bin
$panel->plugins([
    RevivePlugin::make()
        ->enableTenantScoping() // Default: true
        ->enableUserScoping(false)
]);

// Admin panel - see all deleted items
$panel->plugins([
    RevivePlugin::make()
        ->showAllRecords() // Shows all records regardless of user/tenant
        ->authorize(fn () => auth()->user()->isAdmin())
]);

// Custom model filtering
$panel->plugins([
    RevivePlugin::make()
        ->models([Post::class, Comment::class]) // Only show these models
        ->enableUserScoping()
]);

// Completely disable scoping (like v1 behavior)
$panel->plugins([
    RevivePlugin::make()
        ->withoutScoping()
]);
```

#### Examples of configuration for Different Panel Types

[](#examples-of-configuration-for-different-panel-types)

**User Panel Configuration:**

```
// User panel - users only see their own deleted items
public function panel(Panel $panel): Panel
{
    return $panel
        ->id('user')
        ->plugins([
            RevivePlugin::make()
                ->navigationGroup('My Account')
                ->navigationLabel('My Deleted Items')
                ->title('My Recycle Bin')
                ->enableUserScoping(true)
                ->enableTenantScoping(false)
        ]);
}
```

**Admin Panel Configuration:**

```
// Admin panel - see all deleted items across all users/tenants
public function panel(Panel $panel): Panel
{
    return $panel
        ->id('admin')
        ->plugins([
            RevivePlugin::make()
                ->navigationGroup('Administration')
                ->navigationLabel('Global Recycle Bin')
                ->title('All Deleted Items')
                ->showAllRecords()
                ->authorize(fn () => auth()->user()->isAdmin())
        ]);
}
```

**Tenant Panel Configuration:**

```
// Tenant panel - see deleted items for current tenant only
public function panel(Panel $panel): Panel
{
    return $panel
        ->id('tenant')
        ->tenant(Team::class)
        ->plugins([
            RevivePlugin::make()
                ->navigationGroup('Team Management')
                ->navigationLabel('Team Recycle Bin')
                ->title('Team Deleted Items')
                ->enableTenantScoping()
                ->enableUserScoping(false) // All team members can see all team deletions
        ]);
}
```

> ⚠️ The plugin currently supports only models in the `App\Models` namespace. If you want to register a third-party model (e.g., from another package), create a wrapper class that extends it and add the `Recyclable` trait there:

```
namespace App\Models;

use Promethys\Revive\Concerns\Recyclable;
use Vendor\Package\Models\Foo as BaseFoo;

class Foo extends BaseFoo
{
    use SoftDeletes;
    use Recyclable;
}
```

---

Usage
-----

[](#usage)

Once the plugin is installed and configured, you'll see a new page in your Filament navigation menu.
From there, users can restore deleted data or permanently remove it.

### 1. Add the `Recyclable` trait to any soft-deletable model

[](#1-add-the-recyclable-trait-to-any-soft-deletable-model)

```
use Promethys\Revive\Concerns\Recyclable;

class Post extends Model
{
    use SoftDeletes;
    use Recyclable;
}
```

> ℹ️ **Important:** Adding the `Recyclable` trait without using `SoftDeletes` will throw an exception.

### 2. Advanced User Scoping

[](#2-advanced-user-scoping)

#### Custom User and Tenant Detection

[](#custom-user-and-tenant-detection)

Override these methods in your models to customize how users and tenants are detected:

```
class Post extends Model
{
    use SoftDeletes, Recyclable;

    /**
     * Get the user who should be recorded as deleting this model
     * This would override the default method
     */
    public function getDeletedByUser()
    {
        // Custom logic - maybe you store it in a different field
        return $this->deleted_by_user_id ?? auth()->id();
    }

    /**
     * Get the tenant ID for this model
     * This would override the default method
     */
    public function getTenantId()
    {
        // For teams/organizations
        return $this->organization_id;

        // Or for complex tenant relationships
        return $this->workspace->tenant_id ?? null;
    }
}
```

#### Multi-Tenancy Patterns

[](#multi-tenancy-patterns)

**Filament Multi-Tenancy Integration:**The plugin automatically detects Filament tenancy:

```
// In your panel service provider
$panel->plugins([
    RevivePlugin::make()
        ->enableTenantScoping() // Automatically uses filament()->getTenant()
]);
```

**Custom Tenant Models:**

```
class Post extends Model
{
    use SoftDeletes, Recyclable;

    public function getTenantId()
    {
        // For Filament Multi-tenancy
        return filament()->getTenant()->id ?? null;

        // For custom team-based tenancy
        return $this->team_id;

        // For organization-based tenancy
        return $this->organization_id;
    }
}
```

### 3. Optional: Discover existing soft-deleted records

[](#3-optional-discover-existing-soft-deleted-records)

If you already have soft-deleted records before installing the plugin, you can "discover" them by running:

```
php artisan revive:discover-soft-deleted
```

This command will:

- Scan all models that use the `Recyclable` trait
- Find existing soft-deleted records that aren't already tracked in the recycle bin
- Add them to the plugin's tracking system so they appear in the Filament page

#### Command Options

[](#command-options)

**Preview changes without making them:**

```
php artisan revive:discover-soft-deleted --dry-run
```

**Include user/tenant scoping information:**

```
php artisan revive:discover-soft-deleted --with-scope
```

This option attempts to determine who deleted each record and includes tenant information.

**Discover records for a specific model:**

```
php artisan revive:discover-soft-deleted --model=Product
# or use the full class name
php artisan revive:discover-soft-deleted --model="App\Models\Shop\Product"
```

**Combine options:**

```
php artisan revive:discover-soft-deleted --model=Category --dry-run --with-scope
```

#### Example Output

[](#example-output)

```
$ php artisan revive:discover-soft-deleted --with-scope

Discovering soft-deleted records...

🔍 Scanning Category...
   No soft-deleted records found.
🔍 Scanning Comment...
   ✅ 0/3 records discovered
🔍 Scanning Brand...
   ✅ 8/8 records discovered
🔍 Scanning Category...
   ✅ 2/2 records discovered
🔍 Scanning Customer...
   ✅ 0/1 records discovered
🔍 Scanning Order...
   No soft-deleted records found.
🔍 Scanning Product...
   ✅ 12/15 records discovered

🔍 User/tenant scoping information was included

✨ Discovery completed:
   • 29 total soft-deleted records scanned
   • 22 new records discovered and added to recycle bin
```

> **💡 Tips:**
>
> - Run the command with `--dry-run` first to preview what will be discovered, especially on production systems with large amounts of existing data.
> - Use `--with-scope` when upgrading from V1 to V2 to include user/tenant information for existing records.
> - For large systems with extensive output, consider redirecting the command output to a file: `php artisan revive:discover-soft-deleted > discovery-results.txt`

---

Use the table outside the default page
--------------------------------------

[](#use-the-table-outside-the-default-page)

You don't have to register the plugin in your panel to use the table.

Instead, you can render the Livewire component directly in a Blade view:

### Basic Usage

[](#basic-usage)

```
@livewire(\Promethys\Revive\Tables\RecycleBin::class)
```

### Advanced Usage with Scoping

[](#advanced-usage-with-scoping)

```

@livewire(\Promethys\Revive\Tables\RecycleBin::class, [
    'user' => auth()->user(),
    'enableUserScoping' => true,
    'enableTenantScoping' => false,
])

@livewire(\Promethys\Revive\Tables\RecycleBin::class, [
    'showAllRecords' => true,
])

@livewire(\Promethys\Revive\Tables\RecycleBin::class, [
    'tenant' => filament()->getTenant(),
    'enableTenantScoping' => true,
    'enableUserScoping' => false,
])

@livewire(\Promethys\Revive\Tables\RecycleBin::class, [
    'models' => [App\Models\Post::class, App\Models\Comment::class],
    'user' => auth()->user(),
])
```

This is ideal if:

- You don't want to clutter your navigation
- You're not using Filament Panels but still want a recycle bin in your app
- You want different scoping rules for different parts of your application

---

Customization
-------------

[](#customization)

The plugin allows you to fully customize both the **RecycleBin page** and **RecycleBin table** by extending the base classes and registering your custom implementations.

### Customizing the Table

[](#customizing-the-table)

You can extend the `RecycleBin` table component to customize columns, filters, actions, and more.

#### 1. Create a Custom Table Class

[](#1-create-a-custom-table-class)

Create a class that extends `Promethys\Revive\Tables\RecycleBin`:

```