Download the PHP package helgesverre/laravel-prunekeeper without Composer

Prunekeeper

Archive prunable Eloquent records before deletion.

Laravel's Prunable trait lets you automatically clean up old database records.
But once they're gone, they're gone forever.

Prunekeeper hooks into Laravel's pruning process to export records to CSV or SQL before deletion. Archives are compressed and uploaded to any Laravel filesystem disk (S3, local, etc.), giving you a safety net for compliance, auditing, or "just in case."

When you run php artisan model:prune, Prunekeeper automatically:

1. Exports matching records to CSV (or SQL)
2. Compresses the export (ZIP, gzip, bzip2, or tar.gz)
3. Uploads to your configured storage disk
4. Allows Laravel to proceed with deletion

Installation

Optionally publish the configuration:

Requirements: PHP 8.2+ and Laravel 11 or 12.

Basic Usage

Add the ArchivePrunedRecords trait to any model that uses Laravel's Prunable or MassPrunable trait:

That's it. When Laravel prunes the model, Prunekeeper archives the records first.

Using with MassPrunable

Works the same way with MassPrunable (bulk deletion without model events):

Configuration

Export Formats

SQL exports automatically use the correct identifier quoting for your database:

• MySQL/MariaDB: backticks (`)
• PostgreSQL/SQLite: double quotes (")
• SQL Server: square brackets ([])

Compression Drivers

Choose from multiple compression formats:

Configure in config/prunekeeper.php or via environment:

Artisan Commands

Archive without deleting

Archive records without triggering deletion:

Validate configuration

Validate that column configurations are correct:

Run this in CI/CD to catch configuration errors before deployment.

Customization

Export specific columns

By default, all columns are exported. To limit which columns are archived:

If you specify columns that don't exist, Prunekeeper throws an InvalidColumnException with a helpful message showing available columns.

Exclude sensitive columns globally

Apply column filtering across all models. Configure Prunekeeper in a service provider's boot method:

Custom filename

Override the default filename pattern globally:

Or per-model:

Lifecycle hooks

Hook into the archiving process:

Events

Prunekeeper dispatches Laravel events for integration with queues, notifications, or monitoring:

Disable archiving conditionally

Disable archiving for specific models or environments:

Model discovery

The prunekeeper:archive and prunekeeper:validate commands auto-discover models using the ArchivePrunedRecords trait.

By default, models are discovered in app/Models and app/. Configure custom paths:

Glob patterns are supported:

You can also specify models directly via the --model option:

Scheduling

Add pruning to your scheduler in routes/console.php:

Or in Laravel 11+ with bootstrap/app.php:

Preview what will be pruned:

Performance

Prunekeeper handles large datasets efficiently:

• Chunked processing: Records are exported in configurable chunks (default: 1000)
• Streamed uploads: Files are streamed to storage, not loaded entirely into memory
• Configurable chunk size: Adjust PRUNEKEEPER_CHUNK_SIZE based on your constraints

For very large tables (millions of records):

• Run prunekeeper:archive during off-peak hours
• Use a dedicated queue worker for the prune command
• Increase chunk_size if memory allows (improves speed)

Security

When archiving data that may contain sensitive information:

1. Use column filtering: Implement getArchivableColumns() or use resolveColumnsUsing() to exclude sensitive fields
2. Use secure storage: Configure your storage disk with appropriate access controls and encryption
3. Run validation: Use prunekeeper:validate in CI/CD to catch configuration errors

Testing

Changelog

See CHANGELOG for version history.

Contributing

Contributions are welcome! Please see the repository for guidelines.

Security

If you discover a security vulnerability, please email [email protected] instead of using the issue tracker.

Credits

• Helge Sverre

License

The MIT License (MIT). See LICENSE for details.