Laravel provides first-class UUID support through the HasUuids Eloquent trait and the bundled ramsey/uuid library. Switching from UUID v4 to v7 requires overriding one method — no Artisan migration, no column type change. See UUID v4 vs v7 for why the timestamp prefix reduces B-tree fragmentation on PostgreSQL and MySQL.

Eloquent model with UUID v7

<?php
// app/Models/Order.php
namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Concerns\HasUuids;
use Ramsey\Uuid\Uuid;

class Order extends Model
{
    use HasUuids;

    protected $keyType = 'string';
    public $incrementing = false;

    protected $fillable = ['customer_id', 'status'];

    /**
     * Override HasUuids to generate UUID v7 instead of v4.
     */
    public function newUniqueId(): string
    {
        return (string) Uuid::uuid7();
    }
}

HasUuids automatically calls newUniqueId() before each model creation. The override here replaces UUID v4 (Uuid::uuid4()) with UUID v7. See UUID in PHP and Laravel for the full HasUuids API.

Migration — column definition

<?php
// database/migrations/xxxx_create_orders_table.php
use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration {
    public function up(): void
    {
        Schema::create('orders', function (Blueprint $table) {
            $table->uuid('id')->primary();
            $table->uuid('customer_id');
            $table->string('status', 32);
            $table->timestamps();
        });
    }
};

$table->uuid('id') maps to char(36) on MySQL and uuid on PostgreSQL — both accept UUID v4 and v7 identically.

PostgreSQL 18 — server-side generation

<?php
// Migration for PostgreSQL 18+ with native uuidv7()
Schema::create('orders', function (Blueprint $table) {
    $table->uuid('id')->primary()->default(DB::raw('uuidv7()'));
    $table->uuid('customer_id');
    $table->string('status', 32);
    $table->timestamps();
});

DB::raw('uuidv7()') sets the PostgreSQL-layer default — UUID v7 is generated even for raw queries bypassing Eloquent. Requires PostgreSQL 18.

Eloquent relationships with UUID foreign keys

<?php
// app/Models/OrderItem.php
class OrderItem extends Model
{
    use HasUuids;

    protected $keyType = 'string';
    public $incrementing = false;

    public function newUniqueId(): string
    {
        return (string) Uuid::uuid7();
    }

    public function order(): BelongsTo
    {
        return $this->belongsTo(Order::class);
    }
}

// Migration
$table->uuid('order_id');
$table->foreign('order_id')->references('id')->on('orders');

Foreign key columns are declared as $table->uuid('order_id') — no special handling for UUID v7 is needed. The join operates on binary equality regardless of UUID version.

Migrating from UUID v4 to v7

Existing rows keep their UUID v4 values. Only new inserts change:

// Before
public function newUniqueId(): string
{
    return (string) Uuid::uuid4();
}

// After — no migration needed
public function newUniqueId(): string
{
    return (string) Uuid::uuid7();
}

For a full backfill strategy, see Zero-Downtime UUID Migration.

Route model binding and validation

<?php
// routes/api.php
Route::get('/orders/{order}', [OrderController::class, 'show']);

// app/Http/Requests/ShowOrderRequest.php
public function rules(): array
{
    return [
        'id' => ['required', 'uuid'],  // accepts both v4 and v7
    ];
}

Laravel’s uuid validation rule accepts any RFC 9562 UUID version — v4 and v7 both pass. See UUID in OpenAPI for annotating the API schema.

Further reading

External references

Frequently asked questions

How do I use UUID v7 in Laravel with Eloquent?

Use the HasUuids trait and override newUniqueId(): public function newUniqueId(): string { return (string) \Str::uuid7(); }. The ramsey/uuid package (included transitively via laravel/framework) provides Uuid::uuid7() as of version 4.7. No migration is needed — the column type is uuid or char(36) for both v4 and v7. See UUID in PHP and Laravel.

Does Laravel's route model binding work with UUID v7 primary keys?

Yes. Laravel's route model binding resolves models by primary key regardless of UUID version — Route::get('/orders/{order}', ...) works identically with UUID v4 and v7. For custom key resolution, implement getRouteKeyName() on the model as usual.