README

Automatic, rule-based purging of Eloquent models.

Reaper is a Laravel package that safely and declaratively force-deletes soft-deleted models after configurable grace periods — with support for:

⏱ Simple retention periods (30d)
🧩 Composite periods (3w10d1h)
🔗 Multiple conditions (last_activity + deleted_at)
🔀 AND / OR logic
🧠 Custom purge conditions
⏰ Scheduler-driven + manual execution

Features

One global scheduler — no per-model cron jobs
Declarative purge rules on models — custom condition evaluation logic
Custom purge conditions (closures or classes)
Chunked & queue-safe

Installation

composer require naviisml/laravel-reaper

Laravel will auto-discover the service provider.

🚀 Quick Start

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\SoftDeletes;
use Naviisml\Reaper\Concerns\IsReapable;

class User extends Model
{
    use SoftDeletes;
    use IsReapable;

    protected string $period = '30d';
}

That’s it.

Reaper will automatically force-delete users that have been soft-deleted for more than 30 days.

Supported Period Format

Reaper uses a compact, human-readable period syntax:

Unit	Meaning
`h`	hours
`d`	days
`w`	weeks
`m`	months
`y`	years (optional extension)

Examples

30d
12h
3w10d1h
1y2m

Advanced Retention Rules

Note: If all the fields match, but the model is not yet soft deleted, the model will first be soft deleted. If the model doesnt support soft deletes, it will be deleted.

Multiple conditions (AND by default)

protected array $periods = [
    'last_activity' => '1y',
    'deleted_at'    => '1m',
];

Meaning:

last_activity <= now() - 1 year
AND
deleted_at    <= now() - 1 month

Purge Rules

For complex rules, define a $purge definition.

AND (explicit)

protected array $purge = [
    'and' => [
        ['column' => 'deleted_at', 'older_than' => '30d'],
        ['column' => 'last_login', 'older_than' => '1y'],
    ],
];

OR

protected array $purge = [
    'or' => [
        ['column' => 'deleted_at', 'older_than' => '6m'],
        ['column' => 'bounced_at', 'older_than' => '7d'],
    ],
];

Nested conditions

protected array $purge = [
    'and' => [
        ['column' => 'deleted_at', 'older_than' => '30d'],
        [
            'or' => [
                ['column' => 'last_activity', 'older_than' => '1y'],
                ['column' => 'last_login',    'older_than' => '18m'],
            ],
        ],
    ],
];

Closure-based

protected array $purge = [
    'and' => [
        fn ($query) => $query->whereNull('subscription_id'),
        ['column' => 'deleted_at', 'older_than' => '14d'],
    ],
];

Class-based

protected array $purge = [
    'and' => [
        \App\Purge\InactiveTrialCondition::class,
        ['column' => 'deleted_at', 'older_than' => '14d'],
    ],
];

class InactiveTrialCondition
{
    public function apply($query): void
    {
        $query->where('trial_ended', true);
    }
}

Scheduler

Reaper automatically registers a scheduled job:

Runs hourly
Uses withoutOverlapping()
Chunked deletes (chunkById)
Queue-safe

Make sure Laravel’s scheduler is running:

* * * * * php artisan schedule:run

Commands

Run Purge Manually

Dispatch via queue (default)

php artisan reaper:purge

Run synchronously (debug / CI)

php artisan reaper:purge --sync

naviisml / laravel-reaper

Maintainers

Details