README

Independent, framework-agnostic database utilities for Laravel.

Model traits (UUID/NanoID/ULID keys, JSON accessors, slugs, immutability, threaded records, quiet saving), money & datetime casts, schema macros (auditColumns(), softDeletesWithUndo(), configuredMorphs()), an audit observer, soft-delete restore history, backup/restore, connection & schema inspection, a cursor-pagination DTO, and database/maintenance services — designed to be useful in any Laravel app. This package is genuinely independent: it depends only on illuminate/* plus a few small utility libraries (ramsey/uuid, symfony/uid, spatie/laravel-sluggable, and brick/money for the CastMoney cast), and has no dependency on laranail/package-tools or any other Laranail package. Seeding lives in package-tools and the seed console formatter in laranail/console — neither belongs here.

Targets

PHP ^8.3 || ^8.4 || ^8.5
Laravel ^13.0 — depends only on illuminate/database + illuminate/support
Pest ^3.0, Testbench ^11.0
CI matrix: in-memory SQLite + optional MySQL/Postgres legs

Install

composer require laranail/database-tools

DatabaseToolsServiceProvider is auto-discovered and registers the schema macros at boot.

Quick examples

UUID / NanoID / ULID model identifiers

use Illuminate\Database\Eloquent\Model;
use Simtabi\Laranail\DatabaseTools\Concerns\HasUuid;

class Order extends Model
{
    use HasUuid;
    // Auto-sets a v4 UUID on the `uuid` column at creating-time.
    // Override uuidColumn() to use a different column.
}

HasUlid and HasNanoid follow the same pattern. ULIDs are lexicographically sortable by creation time; NanoIDs are 21-char URL-safe by default.

Audit columns + observer

// Migration:
Schema::create('orders', function (Blueprint $t) {
    $t->id();
    $t->string('name');
    $t->auditColumns();           // adds created_by, updated_by, deleted_by
    $t->softDeletesWithUndo();    // adds deleted_at + restored_at
    $t->timestamps();
});

// Model:
use Simtabi\Laranail\DatabaseTools\Observers\AuditObserver;

class Order extends Model
{
    protected static function booted(): void
    {
        static::observe(AuditObserver::class);
    }
}

The observer stamps the authenticated user's ID into the audit columns on create/update/delete; override userIdentifier() if your FK isn't the user's primary key.

JSON column accessors

use Simtabi\Laranail\DatabaseTools\Concerns\HasJsonColumnAccessors;

class Order extends Model
{
    use HasJsonColumnAccessors;

    protected array $jsonColumns = ['metadata', 'snapshot'];
}

$order->metadata = ['shipped_via' => 'fedex'];   // auto-encoded on save
$order->save();
$order->metadata['shipped_via'];                 // 'fedex' — auto-decoded on read

Skips columns already in $casts to avoid double-cast.

Local development

bash .scripts/init.sh
composer test                 # vendor/bin/pest
composer lint                 # pint + phpstan + rector --dry-run
composer audit                # composer audit (security advisories)

Documentation

Hosted at opensource.simtabi.com/database-tools/docs/ (product page: opensource.simtabi.com/database-tools/). The same pages live under docs/:

Guides

Installation — Composer install, auto-discovery, the DatabaseTools facade, targets
Configuration — publishing config/database-tools.php + the history migration; every config key
Architecture — how the facade, schema services, and backup drivers fit together; the independence invariant

Tools & features

Facade — every DatabaseTools static method, with examples
Connection testing — DatabaseConnectionTester: test, driver, version, database name
Schema inspection — DatabaseSchemaInspector: tables, columns, counts
Table verification — DatabaseTableVerifier: verify, detailed report, Laravel tables
Backup & restore — BackupManager, per-driver backups, driver-aware restore, dump import
Traits — model identifier & behavior traits under Concerns/
Casts — CastMoney (brick/money) and CastDatetime
Schema macros — auditColumns(), softDeletesWithUndo(), configuredMorphs(), softDeleteHistory(), BlueprintMacros
Audit observer — AuditObserver + HasAuditObserver: stamping created/updated/deleted by
Soft-delete restore history — HasSoftDeletesWithUndo trait + history table
Eager-load helpers — LoadsAggregatesIfMissing: load-if-missing for counts & aggregates
Cursor pagination — CursorPage DTO over native cursorPaginate()
Events — DatabaseEvents + BaseEvent
BaseModel — the optional base Eloquent model
Services — DatabaseService query/model helpers + MaintenanceService filesystem housekeeping

Examples

Runnable examples — Order.php + OrderMigration.php demonstrating the identifier traits, audit columns, soft-deletes-with-undo, and JSON accessors together
Changelog: CHANGELOG.md

Sister packages

laranail/console — console output, prompts and Artisan command toolkit.
laranail/package-tools — runtime base library for building Laravel packages.
laranail/package-scaffolder — generator that scaffolds new packages.
laranail/laranail — Simtabi's Laravel utility toolbox.

Contributing & security

CONTRIBUTING.md — development guidelines and PR expectations.
SECURITY.md — how to report a vulnerability (opensource@simtabi.com).
CODE_OF_CONDUCT.md — community expectations.

License

MIT. See LICENSE.

laranail / database-tools

Maintainers

Package info

Statistics

Security