Getting Started

Install with composer require webpatser/laravel-uuid. Laravel 5.5+ auto-discovers Webpatser\Uuid\UuidServiceProvider and the Uuid facade alias; on older versions register both in config/app.php.
First place to look is the Uuid class source and the README method table — the class is small and the public API is the whole story.
First use case: generate an identifier and immediately guard inbound input with the new 2.5.2 static validator:

use Webpatser\Uuid\Uuid;

$id = Uuid::generate(4)->string;

if (! Uuid::validate($request->input('id'))) {
    abort(422, 'Invalid identifier');
}

The 2.5.2 addition (Uuid::validate(string): bool) is the lowest-friction entry point — no facade, no config, no DB round-trip. Reach for it before writing another UUID regex.

Implementation Patterns

Model keys. Set $incrementing = false and $keyType = 'string', then assign in a creating hook:

protected static function booted(): void
{
    static::creating(fn ($m) => $m->id ??= Uuid::generate(4)->string);
}

Validation rule. Wrap the new static method so you get localized messages instead of a bare boolean:
```
Validator::extend('uuid', fn ($attr, $value) => Uuid::validate($value));
```
Then 'id' => 'required|uuid' in FormRequests. Keep the closure thin — validate() already handles format checking.
Route model binding. Validate with Uuid::validate() in middleware or a route constraint before binding, so malformed IDs return 404/422 rather than triggering a DB lookup with garbage.
Importing external IDs. Call Uuid::validate($raw) first, then Uuid::import($raw) and check its boolean return. The two-step pattern separates "wrong shape" from "wrong version/bits."
API resources. Cast IDs to string on serialization and use $table->uuid('id')->primary() in migrations — an accidental integer cast silently truncates.
Bulk generation. Loop Uuid::generate(4)->string; if you only ever need v4, Laravel's Str::uuid() is a lighter alternative, but this package earns its place when you need v1/v3/v5.
Testing. Assert Uuid::validate($model->id) instead of hand-rolled regexes — one dependency, clearer intent, and it tracks format changes automatically.

Uuid::generate() returns an object, not a string. You must call ->string or cast. This is the most common mismatch with people coming from Str::uuid().
validate() is format-strict. If your inputs can arrive with braces, uppercase hex, or urn:uuid: prefixes, normalize with trim()/strtolower() first or it will return false.
Watch version choice: generate(1) is time-based and leaks creation order/timing; generate(4) is random. Default to v4 unless you specifically need sortable or namespace UUIDs.
Don't cluster on random UUIDs in high-write tables without a plan — index bloat and write amplification are real. Consider ULID or a separate auto-increment key if throughput matters.
The Uuid facade alias can collide with other packages. In shared libraries, import the FQCN rather than relying on the alias.
The new static validator doesn't replace a full validation rule if you need localized messages or :attribute interpolation — wrap it as shown above.
Debugging false negatives: dump the raw length and hex. Trailing whitespace and non-breaking spaces from form posts are the usual culprits.
Extension point: subclass Uuid or bind your own resolver if you need to accept non-standard formats (braced UUIDs, mixed case) without forking the package.