Download the PHP package iamankitthapar/laravel-data-retention without Composer

Laravel Data Retention

Manage how long your Laravel application keeps data. Define a rule, preview the matching records, then delete, anonymize, or archive them in controlled batches.

Every feature is free under the MIT license. No subscription or license key is required.

Contents

• Features
• Requirements
• Installation
• Your first retention rule
• Actions
• Conditions, exclusions, and grace periods
• Dashboard
• Scheduling
• Configuration
• Commands
• Reports and notifications
• Import and export
• Troubleshooting
• Development and support

Features

• Define rules in PHP or manage stored policies through the dashboard.
• Permanently delete records, replace personal fields, or move records to an archive table.
• Preview eligible records before running a rule.
• Process large tables in chunks with a limit for each execution.
• Exclude protected records and add a grace period.
• Include or select only soft-deleted records.
• Schedule rules with hourly, daily, weekly, monthly, or custom cron frequencies.
• Select database connections for source records and archives.
• Review execution history, optional per-record logs, and summary reports.
• Receive email notifications and import or export stored policies as JSON.

Requirements

You also need a configured Laravel database connection. The dashboard uses your application's authentication system by default.

Installation

Run these commands from your Laravel application's root directory:

Laravel discovers the package automatically. Publishing creates config/data-retention.php and the migrations for these tables:

If package discovery is disabled, register Iamankitthapar\DataRetention\DataRetentionServiceProvider::class in your application's provider list.

Your first retention rule

This walkthrough uses API logs older than six months. Start with a limit of 10 records and preview the result before executing it.

1. Choose or create a model

You can use an existing Eloquent model and table. Replace ApiLog::class and created_at in the examples with your model and date column.

If you do not have an API log model, use the optional setup command:

It creates:

The command creates files; migrate creates the table. It refuses to overwrite an existing ApiLog model or example migration. Laravel also applies your database connection's configured table prefix.

Your application must write its API logs. The example installer does not capture requests or add sample records.

2. Create a retention provider

Replace app/Providers/RetentionServiceProvider.php with:

3. Register the provider

Add the following entry once to your application's provider list:

For example, on Laravel 11–13:

4. Preview the matching records

The preview shows the model, action, eligible-record count, and execution limit. It does not modify records or create a run log.

An empty example table returns zero eligible records. To try the walkthrough locally, open php artisan tinker and create one expired log:

Run the preview again. It should now include that record.

5. Execute and review

After reviewing the preview, run:

This rule permanently deletes up to 10 matching records. Increase the limit when you are ready to process more records. Each execution writes a summary to retention_runs.

Actions

Add the following examples to your retention provider's boot() method. Import the application model you use; models such as User and Order must already exist, and the referenced columns must match your schema.

Delete

Deletion is permanent. For models using Laravel's SoftDeletes trait, this action calls forceDelete().

Anonymize

Keep a record while replacing selected fields:

You can provide fixed values, strategy definitions, or callbacks:

Replacement values must satisfy the table's constraints, including unique indexes and non-null columns. Anonymization does not automatically remove a record from future matches; define conditions that exclude records already processed when needed.

Archive

Copy a record to an archive table, then permanently delete the source:

Create the archive table first, with a schema compatible with the source model's raw attributes. To use another configured Laravel connection:

On the same connection, copying and deleting run in one transaction. Separate connections cannot share an atomic transaction. If deletion fails after a cross-database copy, reconcile the two copies before retrying.

Conditions, exclusions, and grace periods

Filter records

olderThan() calculates the cutoff when the query is built. You can also use retentionPeriod('1 year') for created_at, or retentionPeriod('closed_at', '1 year') for another date column.

Exclude protected records

Only use columns that exist in your table. An exclusion removes matching records from the eligible set.

Add a grace period

Records become eligible after one year plus 30 days. Define the retention period before adding its grace period.

Select soft-deleted records

For models using SoftDeletes:

Choose one mode. By default, soft-deleted records are excluded. The delete and archive actions permanently remove the selected source records.

Select a source connection

Use a connection name defined in your application's config/database.php. Without this setting, the rule uses the model's connection.

Dashboard

After installation, sign in to your application and visit:

The dashboard manages stored policies. Code-defined rules remain in your provider and are listed by retention:list.

To create a stored policy:

1. Select Create policy.
2. Enter a unique name and a full model class, such as App\Models\ApiLog.
3. Choose an action, execution limit, and optional schedule.
4. Enter conditions, exclusions, and action settings using the JSON editors.
5. Save the policy and select Dry run to review the eligible count.
6. Enable the policy and select Run when ready.

Conditions JSON

All conditions must match. Supported operators are =, !=, <>, <, <=, >, >=, LIKE, and NOT LIKE. Dates in stored conditions are fixed cutoffs; use PHP olderThan() rules for rolling periods such as “six months ago.”

Exclusions JSON

Records matching any exclusion are left out. Use [] when no exclusions are needed.

Action configuration JSON

For anonymization:

For archiving:

Delete policies do not need action settings; use {}.

The dashboard uses web and auth middleware by default. Add your application's administrator authorization middleware to restrict policy management. To disable the dashboard, set DATA_RETENTION_DASHBOARD_ENABLED=false in .env.

Scheduling

1. Give a rule a schedule

Add a frequency to the rule in your provider:

Supported frequencies are hourly, daily, weekly, monthly, and cron:<expression>. A timezone is optional:

Stored policies have equivalent Schedule and Timezone fields in the dashboard.

2. Register the schedules

Laravel 11–13: add these calls to routes/console.php:

Laravel 10: add these calls to the existing schedule() method in app/Console/Kernel.php:

Include scheduleStoredPolicies() only if you use scheduled stored policies, and run the package migrations first. These helpers register overlap prevention for each scheduled command.

3. Run Laravel's scheduler

Check the registered schedules:

For local development:

On a Linux server, configure a cron entry that invokes the scheduler every minute:

Configuration

Edit config/data-retention.php after publishing it.

A rule's limit() or a stored policy's execution limit overrides max_records_per_run. Limits apply to each rule execution, including failed attempts. chunk_size controls memory usage; it is not an execution limit. Both values must be positive.

Environment settings:

Commands

Run commands with php artisan:

retention:run without arguments does not execute stored policies. Preview and dry-run commands count matching records; they do not test writes, model events, or archive-table compatibility.

Reports and notifications

Each execution records the eligible count, attempted records, successful records, failures, timestamps, and final status. Enable store_item_logs for individual record identifiers, outcomes, and errors.

Failures trigger email notifications when recipients are configured. Set notifications.notify_on_success to true to receive successful-run notifications too. Emails use your application's Laravel mail configuration. Delivery errors do not change the execution result.

To remove old audit history:

Setting run_log_retention_days supplies a default for that command; it does not schedule cleanup automatically. Audit records are execution logs, not backups or recovery snapshots.

Import and export

Move stored policies between environments:

Without --replace, imports create new policies and duplicate names fail. Imports are validated and saved in a transaction. Code-defined rules and execution history are not included in policy exports.

Imported policies retain their enabled state and schedules. Review them before importing into an environment with an active scheduler, and dry-run each policy before executing it.

Troubleshooting

After changing cached application configuration, run php artisan optimize:clear and rebuild your deployment caches as needed.

Development and support

For contributors working in this package repository:

The CI matrix covers Laravel 10–13. See the requirements analysis for implementation details and scope.

Report bugs or request features through GitHub Issues. Include your Laravel and PHP versions, the relevant rule, and the error message.

This package manages Eloquent retention rules. Relationship-aware deletion, multi-tenancy, approval workflows, object-storage archives, and rollback or recovery are outside its current scope.

License: MIT.