Download the PHP package bernskiold/laravel-data-scrubber without Composer

Laravel Data Scrubber

A Laravel package for scrubbing PII (Personally Identifiable Information) and sensitive data from Eloquent models. Useful for GDPR compliance and data retention policies.

Installation

Install the package via composer:

Optionally publish the configuration file:

If you're using Laravel Horizon, add the data-scrubber queue to your config/horizon.php:

Usage

Implementing Scrubbable on a Model

To make a model scrubbable, implement the Scrubbable interface and use the ScrubsData trait:

Available Scrubbing Strategies

Hashing note: An unsalted hash of low-cardinality data (emails, phone numbers) can be reversed with brute-force or rainbow tables. Set a secret in data-scrubber.strategies.hash.salt (e.g. env('DATA_SCRUBBER_HASH_SALT')) to switch HashStrategy to HMAC and make the result non-reversible. Note that changing the algorithm or salt changes the output, so apply it before scrubbing.

Using Strategy Classes Directly

For more control, you can instantiate strategy classes directly with custom parameters:

Using Custom Callbacks

For more complex scrubbing logic, use the CallbackStrategy:

You can also use the fluent builder pattern:

Timestamp Logging

By default, the package logs when a record was scrubbed by updating a scrubbed_at column. This allows you to:

• Track which records have been scrubbed
• Prevent re-scrubbing already scrubbed records
• Query for scrubbed/unscrubbed records

Add the column to your migration using the provided Blueprint macro:

This creates a nullable timestamp column using the name from your config (data-scrubber.timestamp_column, defaults to scrubbed_at).

To customize timestamp logging behavior, override getScrubOptions() in your model:

To use a different column name:

Query Scopes

When timestamp logging is enabled, the trait provides query scopes:

Scrubbing Individual Records

You can scrub a single record programmatically:

Artisan Commands

The package provides two artisan commands for managing data scrubbing.

Scrub Command

Run the scrubber to process all eligible records:

By default, scrubbing is performed asynchronously using Laravel's queue system. You can configure this behavior globally in the config file or per-model via getScrubOptions().

Config Report Command

View the configuration of all Scrubbable models:

This command displays a summary of all configured models, their fields, scrubbing strategies, and processing options.

Configuration

The configuration file allows you to customize the package behavior:

Publishing a partial config: Laravel merges a published config with the package defaults at the top level only. If you publish config/data-scrubber.php and keep only some keys under a nested array (such as strategies or queue), the unspecified sub-keys fall back to their hard-coded strategy defaults rather than being merged. Keep the full nested arrays in your published file to avoid surprises.

How records are processed

When scrubbing asynchronously, each queued job scrubs a single chunk (chunk_size) of records and, if more remain, dispatches a follow-up job for the next chunk. This keeps individual jobs small on large tables and makes retries safe — a failed job only re-processes its own chunk.

The command and jobs only ever operate on records returned by your scrubbableQuery(), further narrowed to those that have not already been scrubbed (when timestamp logging is enabled). This guards non-idempotent strategies such as HashStrategy against being applied twice on retries or repeated runs.

You can override options on a per-model basis by implementing getScrubOptions() in your model:

Events

When a model is scrubbed, the package dispatches a Scrubbed event. You can register listeners for this event to perform additional actions such as notifying external systems, clearing caches, or triggering other workflows.

Activity Log Integration (Optional)

If you have Spatie Activity Log installed, the package provides two optional listeners for different purposes.

Logging Scrub Activity

To log when records are scrubbed, register the LogScrubbedActivity listener in your EventServiceProvider:

This listener will:

• Only log if Spatie Activity Log is installed
• Only log if the model uses the LogsActivity trait
• Log the field names and strategy names that were applied
• Never log the actual data (neither previous nor scrubbed values)

You can customize the event name and description in your config:

Scrubbing Activity Log Entries

Activity logs often store PII in their properties JSON column (e.g., old/new attribute values). To automatically scrub this data when a model is scrubbed, register the ScrubActivityLogListener:

This listener will scrub the configured property keys (default: old and attributes) in all activity log entries for the scrubbed model, using the same strategies defined in scrubbableFields().

You can customize which property keys are scrubbed in your config:

To customize the behavior per-model, implement the ScrubsActivityLog interface:

Testing

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Credits

• Bernskiold
• All Contributors

License

The MIT License (MIT). Please see License File for more information.