README

Independent, framework-agnostic database utilities for Laravel.

Model traits (UUID, NanoID, ULID, JSON column accessors), schema macros (auditColumns(), softDeletesWithUndo()), observer base classes — designed to be useful in any Laravel app. No dependency on laranail/package-tools or any other Laranail package.

Targets

• PHP ^8.3 || ^8.4
• 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)

Out of scope (deferred to v1.1)

• Polymorphic-relation schema macro
• Eager-load helpers (loadIfMissing, loadAggregateIfMissing)
• Cursor-pagination DTO
• #[Observed] attribute auto-discovery
• HasSoftDeletesWithUndo runtime restore-history table

Documentation

• Primary: opensource.simtabi.com/database-tools/docs/
• Portal: opensource.simtabi.com/database-tools/
• Changelog: CHANGELOG.md

Sister packages

• 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.

License

MIT. See LICENSE.md.