Generate UUID in PHP

UUID v4 - Random (recommended default)

<?php
use Ramsey\Uuid\Uuid;

$uuid = Uuid::uuid4();
echo $uuid->toString(); // → "550e8400-e29b-41d4-a716-446655440000"

UUID v7 - Time-ordered (database PKs)

<?php
use Ramsey\Uuid\Uuid;

// Millisecond-precision timestamp prefix - sorts chronologically
$uuid = Uuid::uuid7();
echo $uuid->toString(); // → "018e8f6a-1b2c-7d3e-9f4a-5b6c7d8e9f0a"

UUID v5 - Deterministic / Namespace-based

<?php
use Ramsey\Uuid\Uuid;

// SHA-1 hash of namespace + name - same inputs always produce the same UUID
$uuid = Uuid::uuid5(Uuid::NAMESPACE_DNS, 'example.com');
echo $uuid->toString(); // → always "cfbff0d1-9375-5685-968c-48ce8b15ae17"

Laravel helpers

<?php
use Illuminate\Support\Str;

// Str::uuid() wraps ramsey/uuid - returns a UuidInterface
$uuid = Str::uuid();
echo (string) $uuid; // → "f47ac10b-58cc-4372-a567-0e02b2c3d479"

// Str::orderedUuid() - time-ordered, better for DB index performance
$orderedUuid = Str::orderedUuid();
echo (string) $orderedUuid;

1. Laravel Eloquent model with UUID primary key

<?php
use Illuminate\Database\Eloquent\Model;
use Illuminate\Support\Str;

class Order extends Model
{
    protected $keyType = 'string';
    public $incrementing = false;

    protected static function boot(): void
    {
        parent::boot();
        static::creating(function (Order $model) {
            if (empty($model->id)) {
                $model->id = (string) Str::uuid();
            }
        });
    }
}

// Or use Laravel's HasUuids trait (Laravel 9+):
// use Illuminate\Database\Eloquent\Concerns\HasUuids;

2. Symfony entity with UUID PK

<?php
use Symfony\Component\Uid\Uuid;
use Doctrine\ORM\Mapping as ORM;

#[ORM\Entity]
class Product
{
    #[ORM\Id]
    #[ORM\Column(type: 'uuid', unique: true)]
    #[ORM\GeneratedValue(strategy: 'CUSTOM')]
    #[ORM\CustomIdGenerator(class: 'doctrine.uuid_generator')]
    private Uuid $id;

    public function __construct()
    {
        $this->id = Uuid::v4();
    }
}

3. API idempotency key

<?php
use Ramsey\Uuid\Uuid;

function chargeCustomer(string $customerId, int $amountCents): array
{
    // Generate once, store in session, reuse on retry
    $idempotencyKey = (string) Uuid::uuid4();

    $response = Http::withHeaders([
        'Idempotency-Key' => $idempotencyKey,
    ])->post('https://api.stripe.com/v1/charges', [
        'customer' => $customerId,
        'amount'   => $amountCents,
        'currency' => 'usd',
    ]);

    return $response->json();
}

How do I generate a UUID in PHP?

ramsey/uuid is the de facto PHP standard with hundreds of millions of downloads. Run composer require ramsey/uuid, then Uuid::uuid4() returns a random v4 and Uuid::uuid7() a time-ordered v7. Laravel ships Str::uuid() built in, and Symfony offers the symfony/uid component.

Is Uuid::uuid4() cryptographically secure?

Yes. Uuid::uuid4() uses the platform CSPRNG (operating system secure random source), suitable for session tokens, API keys, and idempotency keys. Do not use non-cryptographic random sources for security-sensitive identifiers.

What is the difference between UUID v4 and v7 in PHP?

UUID v4 (Uuid::uuid4() or equivalent) is fully random and not sortable. UUID v7 embeds a millisecond timestamp for chronological sorting (RFC 9562). Use v4 for general-purpose IDs; use v7 for database primary keys at scale.

Do I need to install a package for UUID generation in PHP?

Yes. PHP has no built-in UUID generator, so install a library - composer require ramsey/uuid is the standard choice. Laravel bundles Str::uuid() and Symfony provides the symfony/uid component.

How do I validate a UUID string in PHP?

Use the platform's UUID parse/validation function, or test against the RFC 4122 regex: /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i. Always validate external input at API boundaries.

Should I use UUIDs as database primary keys in PHP applications?

UUIDs work well as primary keys for distributed systems. Prefer native UUID/BINARY(16) column types over VARCHAR(36). For very large tables, consider UUID v7 for better B-tree insert locality.

Can I generate UUIDs in PHP without a network connection?

Yes. UUID generation uses local OS entropy sources and does not require network access. Each call is independent and thread-safe on modern platforms.

What output formats are available in PHP?

The standard hyphenated lowercase string (36 chars) is the default. Most APIs also support 32-char hex (no hyphens) and 16-byte binary formats. Use string format for APIs and binary for database storage.

What RFC standards apply to PHP UUID generation?

Version 4 UUIDs follow RFC 4122. UUID v7 follows RFC 9562 (May 2024). Ensure your chosen method produces compliant version and variant bits.

When should I avoid UUID v1?

Avoid UUID v1 in security-sensitive contexts - it embeds MAC address and timestamp information. Prefer v4 (Uuid::uuid4() or equivalent) unless you need legacy Cassandra timeuuid compatibility.