README

A Laravel package that scans your database tables for data quality issues and helps you fix them.

The Problem

Real-world databases accumulate noise over time:

• "john doe", "John Doe", "JOHN DOE" — same person, three records
• " Engineering ", "engineering" — same department, inconsistent casing
• "Managment", "Management" — typo that slipped past validation
• " alice@example.com" — leading space breaking lookups

These issues corrupt reports, break deduplication logic, and make search unreliable. DB Cleaner detects and fixes them without guesswork.

What It Does

Each column gets a quality score (0–100) and a letter grade (A–F). Scores are stored so you can track improvement over time.

Installation

composer require laravelldone/db-cleaner
php artisan vendor:publish --provider="Laravelldone\DbCleaner\DbCleanerServiceProvider"
php artisan migrate

Quick Start

# Scan all tables and see what's wrong
php artisan db-cleaner:scan

# Preview what cleaning would do — no data is touched
php artisan db-cleaner:clean users --column=name --type=whitespace --dry-run

# Apply the fix
php artisan db-cleaner:clean users --column=name --type=whitespace

Configuration

config/db-cleaner.php — the key options:

// Limit to specific tables and columns (empty = scan everything)
'tables' => [
    'users'    => ['name', 'email'],
    'products',
],

// Tables never scanned
'exclude_tables' => ['migrations', 'jobs', 'sessions'],

// Fuzzy duplicate sensitivity (lower = stricter)
'duplicates' => ['fuzzy_threshold' => 2],

// Typo detection similarity (0–100, higher = stricter)
'typos' => ['similarity_threshold' => 85],

CLI

# Scan one table, specific columns
php artisan db-cleaner:scan --table=users --columns=name,email

# View scan history
php artisan db-cleaner:report --table=users --format=json

# Clean types: whitespace | casing | duplicate
php artisan db-cleaner:clean users --column=name --type=casing --dry-run
php artisan db-cleaner:clean users --column=name --type=casing --force

PHP / Facade

use Laravelldone\DbCleaner\Facades\DbCleaner;

$analysis = DbCleaner::scan('users');

$analysis->qualityScore;      // 73.4
$analysis->grade;             // C
$analysis->totalIssueCount(); // 28

// Preview before touching anything
$actions = DbCleaner::previewClean('users', 'name', 'whitespace');

// Apply (confirm required — no accidental changes)
DbCleaner::clean('users', 'name', 'whitespace', confirm: true);

REST API

GET  /api/db-cleaner/status              — overall DB health
GET  /api/db-cleaner/tables              — all tables with scores
GET  /api/db-cleaner/tables/{table}      — detailed column breakdown
POST /api/db-cleaner/tables/{table}/scan — trigger a scan
GET  /api/db-cleaner/history             — score trends over time
POST /api/db-cleaner/clean/preview       — preview cleaning actions
POST /api/db-cleaner/clean/apply         — apply (requires "confirm": true)

Protect the API with a token in .env:

DB_CLEANER_API_TOKEN=your-secret

Dashboard

Visit /db-cleaner for a Livewire dashboard with:

• Quality scores and grades per table
• Issue breakdown chart (Chart.js, no npm required)
• Score trend over time
• Run scans and apply cleaning from the browser

Safety

• No data is ever modified without explicit confirmation — --dry-run in CLI, "confirm": true in the API, confirm: true in PHP
• All cleaning runs inside a DB::transaction()
• Fuzzy analysis is skipped on tables over 5,000 rows by default (max_rows_for_fuzzy) to prevent memory issues

Requirements

• PHP 8.2+
• Laravel 11 or 12
• Livewire 3 or 4

License

MIT