Laravel GDPR Compliance

A comprehensive GDPR/DSGVO compliance toolkit for Laravel applications. Declare personal data on your Eloquent models, manage consent, export subject data, schedule erasure with grace periods and legal hold, and maintain a tamper-evident audit trail — all through a fluent PHP API.

Features

• Fluent personal data declaration on any Eloquent model via a builder DSL
• Registry-driven processing — one config array lists all PII-holding models; no relation graph to maintain
• Subject data export (DSGVO Art. 15) as a structured JSON file, dispatched as a queue job
• Subject data erasure (DSGVO Art. 17) with configurable grace period, three retention modes (delete, anonymize, legal_hold), and deterministic processing order for FK safety
• Per-purpose consent management — append-only consents table, cookie consent helper, middleware
• Policy version tracking with subject acceptance records
• Event-driven audit log (gdpr_audits) that never stores PII values — only field names, event names, and metadata
• 7 built-in anonymizers (name, email, phone, IP address, address, free text, static text) with custom alias support
• Package inventory scanner that reads composer.lock + package-lock.json and writes a JSON snapshot
• 4 Laravel Notifications for deletion requested/cancelled/completed and export ready — overridable via config
• 3 middleware for consent-gated routes, cookie propagation, and deletion-pending auth blocking
• 8 Artisan commands for daily operations, reporting, pruning, and inventory scanning
• 3 queue jobs for async export, deletion processing, and legal hold cleanup

Requirements

• PHP 8.3+
• Laravel 11, 12, or 13

Installation

composer require graystackit/laravel-gdpr-compliance

Publish the config and migrations:

php artisan vendor:publish --tag=gdpr-config
php artisan vendor:publish --tag=gdpr-migrations
php artisan migrate

Optionally publish translations for customization:

php artisan vendor:publish --tag=gdpr-lang

Quick Start

1. Declare personal data on your models

Every model that holds personal data implements PersonalData and uses one or more GDPR traits:

namespace App\Models;

use GraystackIt\Gdpr\Contracts\PersonalData;
use GraystackIt\Gdpr\Enums\RetentionMode;
use GraystackIt\Gdpr\Support\PersonalDataBlueprint;
use GraystackIt\Gdpr\Traits\HasConsentRecords;
use GraystackIt\Gdpr\Traits\HasPersonalData;
use GraystackIt\Gdpr\Traits\IsPersonalDataSubject;
use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable implements PersonalData
{
    use HasPersonalData, IsPersonalDataSubject, HasConsentRecords;

    public function personalData(PersonalDataBlueprint $b): PersonalDataBlueprint
    {
        return $b
            // PII: anonymize AND export
            ->field('name')->anonymizeWith('name')->exportable()
            ->field('email')->anonymizeWith('email')->exportable()
            ->field('phone')->anonymizeWith('phone')->exportable()

            // PII internal: anonymize only, do NOT export
            ->field('password')
                ->anonymizeWith('static_text', ['value' => '[ANONYMIZED]'])

            // Non-PII metadata: export only, never touched
            ->field('created_at')->exportable()
            ->field('locale')->exportable()

            ->retention(
                mode: RetentionMode::Delete,
                gracePeriodDays: 7,  // 0 = immediate, max 30
            )
            ->processOrder(1000); // subject is processed last
    }
}

Related models (that are NOT subjects) use HasPersonalData and define a scope:

namespace App\Models;

use GraystackIt\Gdpr\Contracts\PersonalData;
use GraystackIt\Gdpr\Enums\RetentionMode;
use GraystackIt\Gdpr\Support\PersonalDataBlueprint;
use GraystackIt\Gdpr\Traits\HasPersonalData;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;

class Order extends Model implements PersonalData
{
    use HasPersonalData;

    public function personalData(PersonalDataBlueprint $b): PersonalDataBlueprint
    {
        return $b
            ->field('shipping_address')->anonymizeWith('address')->exportable()
            ->field('billing_email')->anonymizeWith('email')->exportable()
            ->field('total')->exportable()
            ->field('created_at')->exportable()
            ->retention(
                mode: RetentionMode::LegalHold,
                legalHoldDays: 3650,              // 10 years
                legalBasis: '§ 147 AO — tax record retention',
            )
            ->processOrder(100); // children before subject
    }

    public function scopePersonalDataForSubject(Builder $query, Model $subject): Builder
    {
        return match (true) {
            $subject instanceof \App\Models\User => $query->where('user_id', $subject->getKey()),
            default => $query->whereRaw('1 = 0'),
        };
    }
}

2. Register models in config

In config/gdpr.php, list every model that contains personal data:

'models' => [
    \App\Models\User::class,
    \App\Models\Order::class,
    \App\Models\Address::class,
    \App\Models\Comment::class,

    // Vendor models with external profile and scope
    \Vendor\Package\ExternalModel::class => [
        'profile' => \App\Gdpr\Profiles\ExternalProfile::class,
        'scope'   => \App\Gdpr\Scopes\ExternalScope::class,
    ],
],

3. Use the API

use GraystackIt\Gdpr\Facades\GDPR;

// --- Deletion ---
$user->requestDeletion();            // schedule with grace period
$user->deleteImmediately();          // skip grace, process now
$user->cancelDeletion();             // cancel during grace

GDPR::isDeletionPending($user);      // bool
User::whereDeletionPending()->get(); // query scope
User::whereNotDeletionPending()->get();

// --- Export ---
$request = $user->requestExport();   // creates a GdprRequest

// Dispatch the export job manually or let the command do it:
\GraystackIt\Gdpr\Jobs\PreparePersonalDataExportJob::dispatch($request->id);

// --- Consent ---
use GraystackIt\Gdpr\Enums\ConsentPurpose;

$user->grantConsent(ConsentPurpose::Analytics, 'cookie_banner');
$user->withdrawConsent(ConsentPurpose::Marketing);
$user->hasConsent(ConsentPurpose::Analytics);  // bool
$user->consentStatus();                         // ['necessary' => true, 'analytics' => true, ...]

// --- Package inventory ---
GDPR::packageInventory(); // returns array from last scan, or null

Trait Reference

Per-Field DSL

Both behaviors are opt-in per field:

Built-in anonymizer aliases

Register custom anonymizers in config/gdpr.php:

'anonymizers' => [
    // ... built-in aliases
    'ssn' => \App\Gdpr\Anonymizers\SsnAnonymizer::class,
],

Your class must implement GraystackIt\Gdpr\Contracts\Anonymizer.

Retention Modes

Configured per model via ->retention():

->retention(
    mode: RetentionMode::Delete,       // 'delete' | 'anonymize' | 'legal_hold'
    gracePeriodDays: 7,                // 0 = immediate, max 30 (DSGVO Art. 12(3))
    legalHoldDays: 3650,               // required if mode = legal_hold
    legalBasis: '§ 147 AO',           // optional, recommended for legal_hold
)

Processing order

->processOrder(int) controls the sequence when multiple models are processed for the same subject. Lower numbers go first. Convention:

This prevents FK constraint violations when children reference the subject with NOT NULL foreign keys.

Deletion Lifecycle

$user->requestDeletion()
  → gdpr_deletions rows created per affected model (with retention snapshot)
  → Host model rows UNTOUCHED during grace
  → Cancellation at any time: $user->cancelDeletion()

Cron Pass 1 (gdpr:process-deletions, daily):
  → Grace expired: process per snapshot mode (delete/anonymize/legal_hold)
  → Each model follows its OWN retention, sorted by processOrder

Cron Pass 2:
  → Legal hold expired: mandatory forceDelete

During the grace period, nothing is modified on host model rows. The entire grace state lives in the gdpr_deletions table. This means:

• Cancellation is trivial — just flip the state
• The package never forces SoftDeletes on your models
• Auth behavior during grace is your app's decision (see below)

Auth during grace

The package does not lock users out during grace. Use these helpers to implement your preferred UX:

// In your auth logic
if (GDPR::isDeletionPending($user)) {
    // Block login, show banner, redirect, etc.
}

// Or as middleware on auth routes
Route::middleware('gdpr.no-deletion-pending')->group(function () {
    // ...
});

// Or as a query scope
User::whereNotDeletionPending()->where('email', $email)->first();

Consent Management

Database consent (authenticated users)

$user->grantConsent(ConsentPurpose::Analytics, 'cookie_banner');
$user->withdrawConsent(ConsentPurpose::Analytics, 'profile_settings');
$user->hasConsent(ConsentPurpose::Analytics); // latest action wins

The consents table is append-only. Each grant and withdraw is a new row. The current state is the latest row per (subject, purpose).

ConsentPurpose::Necessary always returns true without any database check.

Cookie consent (anonymous visitors)

The ConsentCookieManager reads/writes a JSON cookie (gdpr_consent) with per-purpose booleans:

{
  "necessary": true,
  "analytics": false,
  "marketing": false,
  "embedded_content": true,
  "policy_version": "2026-04",
  "updated_at": "2026-04-08T12:00:00Z"
}

Consent middleware

// Block routes that require marketing consent
Route::middleware('gdpr.consent:marketing')->group(function () {
    // Returns 451 Unavailable For Legal Reasons if consent is missing
});

// Necessary always passes
Route::middleware('gdpr.consent:necessary')->group(function () {
    // Always accessible
});

Audit Log

The gdpr_audits table records deletion/export pipeline events only. It never stores:

• Field values (only field names)
• Raw user agents or full IP addresses
• Consent grants/withdrawals (those live in consents)
• Policy acceptances (those live in gdpr_policy_acceptances)

After a subject is hard-deleted, their audit entries survive as orphans — the subject_id FK points nowhere, which means no re-identification is possible. This is by design.

Logged events: deletion_requested, deletion_scheduled, deletion_cancelled, anonymization_completed, deletion_completed, legal_hold_started, legal_hold_expired, export_requested, export_completed.

Events

The package fires these events for external system integration (e.g., deleting Stripe customers, removing Mailchimp subscribers):

use GraystackIt\Gdpr\Events\PersonalDataErased;

Event::listen(PersonalDataErased::class, function ($event) {
    // $event->deletion->subject_type, $event->deletion->subject_id
    // Clean up Stripe, Mailchimp, S3 avatars, etc.
});

Notifications

Four mail notifications are sent automatically (when config('gdpr.notifications.enabled') is true):

The recipient email is snapshotted into gdpr_requests.notification_email at request time, so notifications work even after the subject's data has been anonymized or deleted. After the final notification, the email is wiped.

Customizing notifications

Text only: publish translations with php artisan vendor:publish --tag=gdpr-lang and edit lang/vendor/gdpr/en/gdpr.php.

Deep customization: override the class in config/gdpr.php:

'notifications' => [
    'deletion_requested' => \App\Notifications\MyDeletionRequested::class,
    'deletion_cancelled' => false,  // disable this notification
    'deletion_completed' => null,   // use package default
    'export_ready' => null,
],

Artisan Commands

Scheduling

Add to your routes/console.php or scheduler:

use Illuminate\Support\Facades\Schedule;

Schedule::command('gdpr:process-deletions')->daily();
Schedule::command('gdpr:cleanup-exports')->daily();
Schedule::command('gdpr:prune')->weekly();

Package inventory

Wire the scanner into your host app's composer.json:

"scripts": {
    "post-update-cmd": [
        "@php artisan gdpr:packages-scan"
    ]
}

Access the inventory programmatically:

$inventory = GDPR::packageInventory();
// Returns: ['generated_at' => '...', 'composer' => [...], 'npm' => [...]]

Pruning & Retention

The gdpr:prune command handles time-based cleanup:

Configure in config/gdpr.php:

'retention' => [
    'audits_days' => 1095,
    'consents_days' => 1095,
    'policy_acceptances_days' => 1095,
    'notification_email_days' => 7,
],

Database Tables

GDPR Compliance Notes

Anonymization vs. pseudonymization

The anonymize mode replaces personal field values with non-identifying placeholders. Whether the result qualifies as true anonymization (GDPR no longer applies) or pseudonymization (GDPR still applies) depends on which fields you configure.

To achieve proper anonymization, ensure you mark all identifying fields — including quasi-identifiers:

• Birthdate + ZIP + gender can uniquely identify 87% of the US population (Sweeney 2000)
• Behavioral patterns in related tables (order timestamps, login times) may re-identify subjects
• External datasets can be joined to remaining data points

The package gives you the tooling. Field selection is your responsibility.

Grace period

• Default 0 days (immediate processing). Opt in per model.
• Hard cap at 30 days (DSGVO Art. 12(3): "without undue delay, in any event within one month").
• During grace, no host model data is modified — cancellation is a clean rollback.

Legal hold

• Enabled via RetentionMode::LegalHold with legalHoldDays.
• The legalBasis field is optional but recommended — the audit log records it for compliance evidence.
• After hold_until expires, the row is mandatorily force-deleted by the cron command.

Backups

The package cannot reach into backup files. If you restore from a backup, pending deletion requests should be re-applied. Document your backup retention in your privacy policy and ensure backups rotate within a documented window.

Subject-to-subject references

When processing Subject A, the package never modifies Subject B — even if B has a foreign key to A. Use onDelete('set null') on FK migrations or listen to the PersonalDataErased event to handle cross-subject cleanup in your app code.

Publishing Reference

Testing

composer test

License

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