README

Laravel Schema Sentinel is a premium database schema integrity and governance suite. It detects and resolves "Schema Drift" (discrepancies between migration blueprints and the actual database state) and provides automated tools to standardize index configurations, audit content syncs, lint migration files, and reverse-engineer legacy tables.

📖 Table of Contents

• Getting Started
  • Introduction
  • Key Features
  • Installation
  • Configuration
• Artisan Commands
  • Auditing Schema Drift (schema:drift)
  • Index Standardization (schema:standardize-indexes)
  • Data Drift Deep Dive (schema:data-drift)
  • Legacy Database Reversing (schema:reverse)
  • Migration File Linter (schema:sentinel-lint)
  • Environment Doctor (schema:sentinel-doctor)
• Programmatic API
  • Drift Auditing
  • Parsing Schema DTOs
  • Index Standardization
  • Data Drift Audits
  • Programmatic Reversing
  • Livewire Component & Blade UI
• Legacy Compatibility
• Changelogs

🚀 Getting Started

Introduction

In modern application deployment, database schemas can easily drift from migration files due to hotfixes, legacy imports, direct database edits, or faulty rollbacks. Schema Sentinel provides a total isolation simulation engine that runs migrations on a shadow database to establish the "ideal" schema, matches it against your live connection, and generates fixes automatically.

Key Features

• 🛡️ Deep Drift Detection: Audits Tables, Columns, Types, Nullability, Defaults, Indexes, and Foreign Keys.
• ⚡ Programmatic Facade: Full API coverage for building custom monitoring dashboards.
• 📐 Index Naming Standardizer: Automatically validates index names against Laravel conventions.
• 🐢 Slow Migration Audit: Pinpoints slow migration files during simulation.
• 🔄 Rollback Audit: Simulates rollbacks to ensure your schema can be cleanly rolled back.
• 🌍 Cross-Environment Sync: Compare your schema against other environments (Staging/Production).
• 🤖 CI/CD Ready: Returns standard shell exit codes for pipeline validation.

Installation

Install the package via Composer:

composer require clcbws/laravel-schema-sentinel

The service provider and facade will be registered automatically.

Configuration

Publish the configuration file:

php artisan vendor:publish --tag="schema-sentinel-config"

This creates config/schema-sentinel.php which allows you to define:

• ignore_tables: Array of table names to exclude from analysis (e.g., migrations, telescope_entries).
• migration_paths: Paths to your migration files (useful for modular applications).
• shadow_connection: Temporary database settings (defaults to isolated SQLite in-memory).
• skip_migrations: List of migration files to skip during shadow simulation.
• notifications: Slack and Discord webhooks for drift alerts.

💻 Artisan Commands

Auditing Schema Drift (schema:drift)

Run the core schema audit to inspect the health of your database:

php artisan schema:drift

Options:

• --fix: Generate a new Laravel migration to align your database.
• --interactive: Confirm column changes step-by-step.
• --sql: Preview generated SQL code in dry-run mode.
• --strict: Report extra tables and columns in the live DB that are not defined in migrations.
• --rollback: Run migrations and roll them back on the shadow DB to verify reversibility.
• --snapshot[=latest]: Use a frozen JSON snapshot for audit speed.
• --tag=name: Limit audits to migrations marked with @sentinel-tag name.

Index Standardization (schema:standardize-indexes)

Inspect your database for non-standard index names and redundant indexes (e.g., column indexes already covered by composite index prefixes):

php artisan schema:standardize-indexes

Options:

• --fix: Generate a migration file to automatically rename deviating indexes and drop duplicate ones.

Data Drift Deep Dive (schema:data-drift)

Audit static lookup or seed tables to verify content consistency between environments:

php artisan schema:data-drift --compare-env=production

Outputs a terminal-based diff table indicating missing, extra, or mismatched rows.

Legacy Database Reversing (schema:reverse)

Reverse-engineer a legacy database into a clean Laravel setup:

php artisan schema:reverse --path=./exports

Options:

• --models: Generate Eloquent Model classes with typed relationships (belongsTo, hasMany) and docblocks.
• --migrations: Generate Blueprint migration files.
• --seeders: Generate seeders filled with sample database records.
• --enums: Generate native PHP 8.4 Backed Enums linked to model casts.

Migration File Linter (schema:sentinel-lint)

Audit your codebase migrations for anti-patterns that can cause drift:

php artisan schema:sentinel-lint

Scans for:

1. Raw DB::statement calls.
2. Hardcoded platform-specific string default dates (like 'CURRENT_TIMESTAMP').
3. Unsafe Schema::drop calls lacking IfExists.

Environment Doctor (schema:sentinel-doctor)

Run the health advisor to verify your environment configurations (PHP version, PDO drivers, shadow connection configs):

php artisan schema:sentinel-doctor

Help Guides & Spelling Matcher (schema:help)

Get detailed command help, configuration tips, and options. If you make a typo, the built-in Levenshtein suggestion engine will automatically suggest the correct command:

php artisan schema:help drft

🔌 Programmatic API

You can integrate Sentinel programmatically inside controllers, dashboards, or deployment hooks using the Sentinel facade.

Drift Auditing

use Sentinel\SchemaSentinel\Facades\Sentinel;

$diff = Sentinel::check(strict: true);

if ($diff->hasDifferences()) {
    // Schema has drifted
    $healthScore = $diff->getHealthScore();
    $missingTables = $diff->missingTables;
}

Parsing Schema DTOs

Extract structured metadata representing your database layout:

$tables = Sentinel::parse(); // Returns array of TableDefinition DTOs

Index Standardization

Run the index analyzer programmatically:

$results = Sentinel::standardizeIndexes();
// Returns array with 'deviations' and 'redundant' indexes

Data Drift Audits

Audit data consistency against a target connection:

$dataDrift = Sentinel::dataDrift('production');

Programmatic Reversing

Trigger the reverse engineering generator from code:

$results = Sentinel::reverse([
    'path' => base_path('exports'),
    'models' => true,
    'migrations' => true,
    'seeders' => false,
    'enums' => true,
]);

Livewire Component & Blade UI

Display database integrity metrics inside your admin templates:

<!-- Livewire Component -->
<livewire:sentinel-database-health />

Or check programmatically in Blade layouts:

@if(\Sentinel\SchemaSentinel\Facades\Sentinel::check()->hasDifferences())
    <div class="alert alert-danger">
        Warning: Database schema drift detected!
    </div>
@endif

⚠️ Legacy Compatibility

While the latest version of this package requires Laravel 13.x and PHP 8.4+, developers running Laravel 11.x or 12.x (with PHP 8.2 or 8.3) can use the stable v1.6.0 release:

composer require clcbws/laravel-schema-sentinel:~1.6.0

📄 Changelogs

Latest Release: v2.0.0

• Index Standardizer & Optimizer: Detects duplicate indexes and enforces Laravel naming conventions.
• Data Drift Engine: Audits static data tables across different database connections.
• Legacy Bridge Generator: Reverse-engineers databases into modern migrations, models with relationships, seeders, and PHP 8.4 Backed Enums.
• PHP 8.4 / Laravel 13 Alignment: Full type-safety compliance, strict typing enabled file-wide, and console command attributes.
• CLI Bug Fixes: Corrected infinite loop retry states, docs property errors, and bigInt mappings.

For past version releases, see changelogs/v1.0.0.md and changelogs/v1.6.0.md.

🤝 Credits

• Author: Ahtesham
• Company: Broadway Web Service
• License: MIT License