Laravel Essentials

Casts

Casts, concerns and contracts

AsDateTime

Foxws\Essentials\Casts\AsDateTime stores a date as a date-time string in app.timezone, whatever timezone it was given in, and reads blank values as null. Dates come from the Date factory, so they're immutable when ImmutableDates runs.

Laravel's own datetime and immutable_datetime casts keep the clock time and drop the offset. With app.timezone set to Europe/Amsterdam:

Value immutable_datetime stores AsDateTime stores
'2026-01-01 12:00:00+00:00' 2026-01-01 12:00:00 2026-01-01 13:00:00
'' '' null

That matters for ISO strings from an API, or dates in a user's timezone. Values from now() are already in the app timezone either way.

protected function casts(): array
{
    return [
        'published_at' => AsDateTime::class,
    ];
}

HasUlid

Foxws\Essentials\Concerns\HasUlid keeps a model's auto-incrementing primary key, and fills a unique ulid column to expose instead of the id. Unlike Laravel's HasUlids, the primary key stays an integer.

Add Laravel's #[RouteKey] attribute to make routes bind to the ULID, so ids aren't exposed in URLs:

use Foxws\Essentials\Concerns\HasUlid;
use Illuminate\Database\Eloquent\Attributes\RouteKey;

#[RouteKey('ulid')]
class Invoice extends Model
{
    use HasUlid;
}
Schema::create('invoices', function (Blueprint $table) {
    $table->id();
    $table->ulid('ulid')->unique();
    // ...
});

Invoice::findFromUlid($ulid) finds a model by its ULID, and returns the model as-is when you pass one. Like Eloquent's findOr() and findOrFail(), there's a version that calls a callback and one that throws a ModelNotFoundException when no model has the ULID:

Invoice::findFromUlidOr($ulid, fn () => abort(404));
Invoice::findFromUlidOrFail($ulid);

A value that isn't a valid ULID finds nothing without querying the database, like route model binding does. They look in the ulid column; pass a column to look somewhere else:

Invoice::findFromUlid($ulid, 'public_id');
Invoice::findFromUlidOrFail($ulid, 'public_id');

To look a ULID up inside a query, such as a relation or with other constraints, use the whereUlid() scope. It takes one ULID or a list, and the same optional column. The builder's first(), firstOr() and firstOrFail() work on it as usual:

$customer->invoices()->whereUlid($ulid)->firstOrFail();
Invoice::paid()->whereUlid($ulid)->first();
Invoice::whereUlid([$first, $second])->get();

Values that aren't valid ULIDs are left out, so they match nothing.

Enumerable

Foxws\Essentials\Contracts\Enumerable is a backed enum with human-readable labels, e.g. to build select options. Write label() with an exhaustive match, and use the HasLabels trait, which builds labels() from it:

use Foxws\Essentials\Concerns\HasLabels;
use Foxws\Essentials\Contracts\Enumerable;

enum InvoiceStatus: string implements Enumerable
{
    use HasLabels;

    case Draft = 'draft';
    case Paid = 'paid';

    public function label(): string
    {
        return match ($this) {
            self::Draft => __('Draft'),
            self::Paid => __('Paid'),
        };
    }
}

PHPStan reports a match that misses a case, and PHP throws an UnhandledMatchError if one slips through, so a new case can't silently go without a label. InvoiceStatus::labels() gives ['draft' => 'Draft', 'paid' => 'Paid'], which is what spatie/laravel-options reads in Options::forEnum().