Uuid Laravel Package

Getting Started

Install the package via Composer:

composer require ramsey/uuid

Then start generating UUIDs immediately in your code:

use Ramsey\Uuid\Uuid;

$uuid = Uuid::uuid4(); // Standard random UUID
echo $uuid->toString(); // e.g., "550e8400-e29b-41d4-a716-446655440000"

The README and official docs at https://uuid.ramsey.dev are the best first references. Begin with generating versions (v1–v8), converting between string/bytes/integer representations, and validating UUIDs.

Implementation Patterns

• Model Keys: Use Ramsey\Uuid\Uuid::uuid4() as Eloquent model keys by setting $keyType = 'string' and $incrementing = false. Override getAttributeValue() for custom string casting if needed.
• Database Storage: Store UUIDs as CHAR(36) (human-readable) or BINARY(16) (space-efficient). Use getBytes() + bin2hex() or Doctrine’s custom DBAL types for binary storage.
• Monotonic UUIDs: For ordered IDs (e.g., in logs, timelines), prefer Uuid::uuid7() (time-based, sortable) over deprecated v6/v1. Avoid v1 due to MAC address exposure.
• Testing: Use Uuid::fromString('00000000-0000-0000-0000-000000000000') for nil, or Ramsey\Uuid\Nonstandard\Uuid::uuid4() with custom factory for deterministic test values.
• Integration: Leverage Uuid::isValid() for input sanitization, and Ramsey\Uuid\Converter\Number\GenericNumberConverter for high-precision arithmetic with integers.
• Extensibility: Customize generator/codec via UuidFactoryInterface (e.g., replace random generator for CI or performance) or use TypedValue types for rich domain modeling.

Gotchas and Tips

• v4 collisions: Extremely rare but not impossible—use v7 if monotonic ordering is critical. For high-throughput systems, avoid mt_rand() fallbacks; prefer paragonie/constant_time_encoding or random_bytes().
• Case sensitivity: Uuid::isValid() accepts uppercase/lowercase, but string comparisons may fail. Normalize with (string) $uuid or strtolower() before DB queries.
• Decoding failures: Uuid::fromBytes() and Uuid::fromHexadecimal() throw InvalidArgumentException if lengths don’t match—always wrap in try/catch or validate first.
• Serialization: UuidInterface implements JsonSerializable, but serialize() isn’t supported. Use toString() or getBytes() in custom __sleep() implementations.
• PHPStan warnings: Ensure you have @pure-aware level 5+ config—some static analyzers misinfer immutability on methods like compareTo() or getFields().
• Deprecated generators: CombGenerator, TimestampFirstCombCodec, and OrderedTimeCodec are deprecated as of 4.8.0; migrate to v6 (reordered time) or v7 (unix time) to stay future-proof.
• Factory pattern: Use Ramsey\Uuid\UuidFactory to inject dependencies in containers (e.g., custom node providers or entropy sources). Example:

  $factory = new UuidFactory($generator, $codec, $uuidBuilder);
  $uuid = $factory->uuid4();
  

• Upgrading v3→v4: No BC break in generation, but type hints changed (Ramsey\Uuid\UuidInterface replaces Moontoast\Math\BigNumber). Use ramsey/uuid-doctrine for Doctrine 2+ compatibility.