Preserving Data Integrity with Laravel Soft Deletes for Recovery and Compliance

Laravel's soft delete functionality provides a sophisticated approach to data management that maintains complete records while allowing logical deletion. This feature proves essential for compliance requirements, data recovery scenarios, and maintaining referential integrity across complex applications.

#Setting Up Soft Deletes

Add the required database column using Laravel's migration helper:

Schema::table('documents', function (Blueprint $table) {
    $table->softDeletes();
});

Enable soft deletes in your Eloquent model:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\SoftDeletes;

class Document extends Model
{
    use SoftDeletes;
    
    protected $fillable = ['title', 'content', 'category', 'author_id'];
}

Basic operations with soft deletes work seamlessly:

// Soft delete a document
$document->delete();

// Restore a soft-deleted document  
$document->restore();

// Check if a document is soft deleted
if ($document->trashed()) {
    // Handle soft-deleted state
}

Consider a legal document management system where maintaining complete audit trails and ensuring regulatory compliance are paramount. Organizations need to track document lifecycle changes while preserving historical data for litigation and compliance purposes:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\SoftDeletes;
use Illuminate\Database\Eloquent\Relations\HasMany;
use Illuminate\Database\Eloquent\Relations\BelongsTo;

class LegalDocument extends Model
{
    use SoftDeletes;

    protected $fillable = [
        'title', 'document_type', 'classification', 'retention_period',
        'author_id', 'department_id', 'version', 'content_hash'
    ];

    protected $casts = [
        'retention_expires_at' => 'datetime',
        'archived_at' => 'datetime',
    ];

    public function author(): BelongsTo
    {
        return $this->belongsTo(User::class, 'author_id');
    }

    public function department(): BelongsTo
    {
        return $this->belongsTo(Department::class);
    }

    public function revisions(): HasMany
    {
        return $this->hasMany(DocumentRevision::class);
    }

    public function annotations(): HasMany
    {
        return $this->hasMany(DocumentAnnotation::class);
    }

    protected static function booted()
    {
        static::deleting(function ($document) {
            // Cascade soft delete to related annotations
            $document->annotations()->delete();
            
            // Log deletion for audit trail
            ActivityLog::create([
                'action' => 'document_deleted',
                'subject_type' => LegalDocument::class,
                'subject_id' => $document->id,
                'user_id' => auth()->id(),
                'properties' => [
                    'document_title' => $document->title,
                    'classification' => $document->classification,
                    'deletion_reason' => request()->input('deletion_reason'),
                ],
            ]);
        });

        static::restoring(function ($document) {
            // Restore related annotations
            $document->annotations()->restore();
            
            // Log restoration
            ActivityLog::create([
                'action' => 'document_restored',
                'subject_type' => LegalDocument::class,
                'subject_id' => $document->id,
                'user_id' => auth()->id(),
                'properties' => [
                    'document_title' => $document->title,
                    'restored_from' => $document->deleted_at,
                ],
            ]);
        });
    }

    public function scopeAwaitingDestruction($query)
    {
        return $query->onlyTrashed()
                    ->where('retention_expires_at', '<', now())
                    ->where('deleted_at', '<', now()->subMonths(6));
    }

    public function isPermanentlyDeletable(): bool
    {
        return $this->trashed() && 
               $this->retention_expires_at < now() &&
               $this->deleted_at < now()->subMonths(6);
    }
}

class DocumentRevision extends Model
{
    use SoftDeletes;

    protected $fillable = [
        'document_id', 'version_number', 'change_summary', 
        'content_diff', 'author_id'
    ];

    public function document(): BelongsTo
    {
        return $this->belongsTo(LegalDocument::class, 'document_id');
    }
}

class DocumentAnnotation extends Model
{
    use SoftDeletes;

    protected $fillable = [
        'document_id', 'author_id', 'annotation_text', 
        'page_number', 'position_data'
    ];

    public function document(): BelongsTo
    {
        return $this->belongsTo(LegalDocument::class, 'document_id');
    }
}

Advanced querying capabilities handle complex compliance scenarios:

<?php

namespace App\Services;

use App\Models\LegalDocument;
use Illuminate\Support\Collection;

class DocumentComplianceService
{
    public function getActiveDocuments(): Collection
    {
        return LegalDocument::where('classification', '!=', 'archived')
                           ->orderBy('updated_at', 'desc')
                           ->get();
    }

    public function getDeletedDocumentsForAudit(): Collection
    {
        return LegalDocument::onlyTrashed()
                           ->with(['author', 'department'])
                           ->orderBy('deleted_at', 'desc')
                           ->get();
    }

    public function getAllDocumentsIncludingDeleted(): Collection
    {
        return LegalDocument::withTrashed()
                           ->with(['author', 'department', 'annotations'])
                           ->orderBy('created_at', 'desc')
                           ->get();
    }

    public function findDocumentForLitigation(int $documentId): ?LegalDocument
    {
        // Include soft-deleted documents for legal discovery
        return LegalDocument::withTrashed()
                           ->with(['revisions.author', 'annotations'])
                           ->find($documentId);
    }

    public function getExpiredDocumentsAwaitingDestruction(): Collection
    {
        return LegalDocument::awaitingDestruction()
                           ->with(['author', 'department'])
                           ->get();
    }

    public function performRetentionCleanup(): array
    {
        $expiredDocuments = $this->getExpiredDocumentsAwaitingDestruction();
        $deletedCount = 0;
        $errors = [];

        foreach ($expiredDocuments as $document) {
            try {
                if ($document->isPermanentlyDeletable()) {
                    // Force delete after retention period
                    $document->forceDelete();
                    $deletedCount++;
                    
                    ActivityLog::create([
                        'action' => 'document_permanently_deleted',
                        'subject_type' => LegalDocument::class,
                        'subject_id' => $document->id,
                        'properties' => [
                            'document_title' => $document->title,
                            'retention_expired' => $document->retention_expires_at,
                            'soft_deleted_at' => $document->deleted_at,
                        ],
                    ]);
                }
            } catch (\Exception $e) {
                $errors[] = [
                    'document_id' => $document->id,
                    'error' => $e->getMessage(),
                ];
            }
        }

        return [
            'deleted_count' => $deletedCount,
            'errors' => $errors,
        ];
    }

    public function restoreDocumentWithRelated(int $documentId): bool
    {
        $document = LegalDocument::withTrashed()->find($documentId);
        
        if (!$document || !$document->trashed()) {
            return false;
        }

        // Restore document and all related annotations
        $document->restore();
        
        return true;
    }
}

class DocumentController extends Controller
{
    public function __construct(
        private DocumentComplianceService $complianceService
    ) {}

    public function destroy(LegalDocument $document, Request $request)
    {
        $request->validate([
            'deletion_reason' => 'required|string|max:500',
        ]);

        $document->delete();

        return response()->json([
            'message' => 'Document soft deleted successfully',
            'can_restore' => true,
            'deleted_at' => $document->fresh()->deleted_at,
        ]);
    }

    public function restore(int $documentId)
    {
        $restored = $this->complianceService->restoreDocumentWithRelated($documentId);

        if (!$restored) {
            return response()->json(['message' => 'Document not found or not deleted'], 404);
        }

        return response()->json(['message' => 'Document restored successfully']);
    }

    public function audit()
    {
        return response()->json([
            'active_documents' => $this->complianceService->getActiveDocuments()->count(),
            'deleted_documents' => $this->complianceService->getDeletedDocumentsForAudit()->count(),
            'pending_destruction' => $this->complianceService->getExpiredDocumentsAwaitingDestruction()->count(),
        ]);
    }
}

Soft deletes in Laravel provide a comprehensive solution for maintaining data integrity while supporting complex business requirements. This approach enables robust audit trails, facilitates compliance with data retention policies, and ensures recovery capabilities without compromising application performance.